stura-infra/hosts/redmine/README.md

# Redmine Host - Project Management

Redmine project management system at 141.56.51.15 running in an LXC container.

## Overview

- **Hostname**: pro
- **FQDN**: pro.htw.stura-dresden.de
- **IP Address**: 141.56.51.15
- **Type**: Proxmox LXC Container
- **Services**: Redmine (Rails), Nginx (reverse proxy), OpenSSH

## Services

### Redmine

Redmine is a flexible project management web application:
- **Port**: 3000 (local only, not exposed)
- **Database**: SQLite (default NixOS configuration)
- **SMTP relay**: mail.htw.stura-dresden.de:25
- **Image processing**: ImageMagick enabled
- **PDF support**: Ghostscript enabled
- **Auto-upgrade**: Enabled (Redmine updates automatically)

**Features:**
- Issue tracking
- Project wikis
- Time tracking
- Gantt charts and calendars
- Multiple project support
- Role-based access control

### Nginx

Nginx acts as a reverse proxy:
- Receives HTTPS requests (TLS termination)
- Forwards to Redmine on localhost:3000
- Manages ACME/Let's Encrypt certificates
- Default virtual host (catches all traffic to this IP)

**Privacy configuration:**
- Access logs: Disabled
- Error logs: Emergency level only (`/dev/null emerg`)

### Email Delivery

SMTP is configured for email notifications:
- **Delivery method**: SMTP
- **SMTP host**: mail.htw.stura-dresden.de
- **SMTP port**: 25
- **Authentication**: None (internal relay)

Redmine can send notifications for:
- New issues
- Issue updates
- Comments
- Project updates

## Deployment

See the [main README](../../README.md) for deployment methods.

### Initial Installation

**Using nixos-anywhere:**
```bash
nix run github:nix-community/nixos-anywhere -- --flake .#redmine --target-host root@141.56.51.15
```

**Using container tarball:**
```bash
nix build .#containers-redmine
scp result/tarball/nixos-system-x86_64-linux.tar.xz root@proxmox-host:/var/lib/vz/template/cache/
pct create 115 /var/lib/vz/template/cache/nixos-system-x86_64-linux.tar.xz \
  --hostname pro \
  --net0 name=eth0,bridge=vmbr0,ip=141.56.51.15/24,gw=141.56.51.254 \
  --memory 2048 \
  --cores 2 \
  --rootfs local-lvm:10 \
  --unprivileged 1 \
  --features nesting=1
pct start 115
```

### Updates

```bash
# From local machine
nixos-rebuild switch --flake .#redmine --target-host root@141.56.51.15

# Or use auto-generated script
nix run .#redmine-update
```

## Post-Deployment Steps

After deploying for the first time:

1. **Access the web interface:**
   ```
   https://pro.htw.stura-dresden.de
   ```

2. **Complete initial setup:**
   - Log in with default admin credentials (admin/admin)
   - **Immediately change the admin password**
   - Configure basic settings (Settings → Administration)

3. **Configure LDAP authentication** (optional):
   - Navigate to Administration → LDAP authentication
   - Add LDAP server if using external identity provider
   - Configure attribute mapping

4. **Set up projects:**
   - Create projects via Administration → Projects → New project
   - Configure project modules (issues, wiki, time tracking, etc.)
   - Set up roles and permissions

5. **Configure email notifications:**
   - Administration → Settings → Email notifications
   - Verify SMTP settings are working
   - Set default email preferences
   - Test email delivery

6. **Configure issue tracking:**
   - Administration → Trackers (Bug, Feature, Support, etc.)
   - Administration → Issue statuses
   - Administration → Workflows

## Integration with Proxy

The central proxy at 141.56.51.1 handles:
- **SNI routing**: Routes HTTPS traffic for pro.htw.stura-dresden.de
- **HTTP routing**: Routes HTTP traffic and redirects to HTTPS
- **ACME challenges**: Forwards certificate verification requests

This host manages its own ACME certificates. Nginx handles TLS termination.

## Troubleshooting

### SMTP connection issues

If email notifications are not being sent:

```bash
# Check Redmine email configuration
cat /var/lib/redmine/config/configuration.yml | grep -A 10 email_delivery

# Test SMTP connectivity
telnet mail.htw.stura-dresden.de 25

# View Redmine logs
tail -f /var/lib/redmine/log/production.log

# Check mail queue (if using local sendmail)
mailq
```

**Solution**: Verify the SMTP relay (mail.htw.stura-dresden.de) is reachable and accepting connections on port 25.

### ImageMagick/Ghostscript paths

If image processing or PDF thumbnails fail:

```bash
# Check ImageMagick installation
which convert
/run/current-system/sw/bin/convert --version

# Check Ghostscript installation
which gs
/run/current-system/sw/bin/gs --version

# Test image conversion
/run/current-system/sw/bin/convert test.png -resize 100x100 output.png

# View Redmine logs for image processing errors
grep -i imagemagick /var/lib/redmine/log/production.log
```

**Solution**: ImageMagick and Ghostscript are enabled via NixOS config. Paths are automatically configured.

### Database migration failures

If Redmine fails to start after an update:

```bash
# Check Redmine service status
systemctl status redmine

# View Redmine logs
journalctl -u redmine -f

# Manually run database migrations (if needed)
cd /var/lib/redmine
sudo -u redmine bundle exec rake db:migrate RAILS_ENV=production

# Check database schema version
sudo -u redmine bundle exec rake db:version RAILS_ENV=production
```

**Solution**: Auto-upgrade is enabled, but migrations can sometimes fail. Check logs for specific errors.

### Nginx proxy configuration

If the web interface is unreachable:

```bash
# Check Nginx configuration
nginx -t

# Check Nginx status
systemctl status nginx

# View Nginx error logs
journalctl -u nginx -f

# Test local Redmine connection
curl http://127.0.0.1:3000
```

**Solution**: Verify Nginx is proxying correctly to localhost:3000 and that Redmine is running.

### Redmine service not starting

If Redmine fails to start:

```bash
# Check service status
systemctl status redmine

# View detailed logs
journalctl -u redmine -n 100

# Check database file permissions
ls -l /var/lib/redmine/db/

# Check configuration
ls -l /var/lib/redmine/config/

# Try starting manually
cd /var/lib/redmine
sudo -u redmine bundle exec rails server -e production
```

**Solution**: Check logs for specific errors. Common issues include database permissions, missing gems, or configuration errors.

### ACME certificate issues

If HTTPS is not working:

```bash
# Check ACME certificate status
systemctl status acme-pro.htw.stura-dresden.de

# View ACME logs
journalctl -u acme-pro.htw.stura-dresden.de -f

# Check certificate files
ls -l /var/lib/acme/pro.htw.stura-dresden.de/

# Manually trigger renewal
systemctl start acme-pro.htw.stura-dresden.de
```

**Solution**: Ensure DNS points to proxy (141.56.51.1) and the proxy forwards ACME challenges to this host.

## Files and Directories

- **Redmine home**: `/var/lib/redmine/`
- **Configuration**: `/var/lib/redmine/config/`
  - `configuration.yml` - Email and general settings
  - `database.yml` - Database configuration
- **Logs**: `/var/lib/redmine/log/production.log`
- **Database**: `/var/lib/redmine/db/` (SQLite)
- **Files/attachments**: `/var/lib/redmine/files/`
- **Plugins**: `/var/lib/redmine/plugins/`
- **Themes**: `/var/lib/redmine/public/themes/`

## Network

- **Interface**: eth0 (LXC container)
- **IP**: 141.56.51.15/24
- **Gateway**: 141.56.51.254
- **Firewall**: Ports 22, 80, 443 allowed

## Configuration Details

- **Redmine version**: Latest from NixOS 25.11
- **Database**: SQLite (default)
- **Web server**: Nginx (reverse proxy)
- **Application server**: Puma (default Rails server)
- **Ruby version**: Determined by NixOS Redmine package
- **SMTP**: mail.htw.stura-dresden.de:25
- **ImageMagick**: Enabled (minimagick)
- **Ghostscript**: Enabled (PDF support)
- **Font**: Liberation Sans Regular

## Automatic Maintenance

- **Auto-upgrade**: Enabled (system automatically updates)
- **Auto-reboot**: Allowed (system may reboot for updates)
- **Store optimization**: Automatic
- **Garbage collection**: Automatic (delete older than 42 days)

## Useful Commands

```bash
# Access Redmine console
cd /var/lib/redmine
sudo -u redmine bundle exec rails console -e production

# Run rake tasks
sudo -u redmine bundle exec rake <task> RAILS_ENV=production

# Database backup
sudo -u redmine cp /var/lib/redmine/db/production.sqlite3 /backup/redmine-$(date +%Y%m%d).sqlite3

# View running processes
ps aux | grep redmine

# Restart Redmine
systemctl restart redmine
```

## See Also

- [Main README](../../README.md) - Deployment methods and architecture
- [Proxy README](../proxy/README.md) - How the central proxy routes traffic
- [Redmine Documentation](https://www.redmine.org/projects/redmine/wiki/Guide)
- [Redmine Administration Guide](https://www.redmine.org/projects/redmine/wiki/RedmineAdministration)
- [NixOS Redmine Options](https://search.nixos.org/options?query=services.redmine)