rick-infra/docs/sigvild-gallery-deployment.md

# Sigvild Gallery Deployment Guide

## Quick Start

Deploy the complete Sigvild Wedding Gallery with PocketBase API and SvelteKit frontend.

## Prerequisites Setup

### 1. Vault Password Configuration

Create encrypted passwords for the gallery authentication:

```bash
# Create vault passwords (run from rick-infra directory)
ansible-vault encrypt_string 'your-host-password-here' --name 'vault_sigvild_host_password'
ansible-vault encrypt_string 'your-guest-password-here' --name 'vault_sigvild_guest_password'
```

Add the encrypted strings to `host_vars/arch-vps/main.yml`:

```yaml
# Add to host_vars/arch-vps/main.yml
vault_sigvild_host_password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          66386439653765386...
          
vault_sigvild_guest_password: !vault |
          $ANSIBLE_VAULT;1.1;AES256  
          33663065383834313...
```

### 2. DNS Configuration

Ensure these domains point to your server:
- `sigvild.no` → Frontend static site
- `api.sigvild.no` → API backend proxy

### 3. Project Structure

Ensure the sigvild-gallery project is adjacent to rick-infra:

```
~/
├── rick-infra/          # This repository
└── sigvild-gallery/     # Sigvild gallery project
    ├── build_tmp/       # Production builds
    ├── sigvild-kit/     # Frontend source
    └── main.go          # Backend source
```

## Deployment Commands

### Full Infrastructure + Gallery

Deploy everything including Sigvild Gallery:

```bash
ansible-playbook site.yml
```

### Gallery Only

Deploy just the Sigvild Gallery service:

```bash
ansible-playbook playbooks/deploy-sigvild.yml
```

### Selective Updates

Update specific components:

```bash
# Frontend only (quick static file updates)
ansible-playbook site.yml --tags="frontend"

# Backend only (API service updates)  
ansible-playbook site.yml --tags="backend"

# Caddy configuration only
ansible-playbook site.yml --tags="caddy"

# Just build process (development)
ansible-playbook site.yml --tags="build"
```

## Architecture Overview

```
Internet
    ↓
Caddy (Auto HTTPS)
    ├── sigvild.no → /var/www/sigvild-gallery/ (Static Files)
    └── api.sigvild.no → localhost:8090 (PocketBase API)
            ↓
        Go Binary (sigvild-gallery-server)
            ↓
        SQLite Database + File Storage
```

## Service Management

### Status Checks

```bash
# Gallery API service
systemctl status sigvild-gallery

# Caddy web server  
systemctl status caddy

# View gallery logs
journalctl -u sigvild-gallery -f

# View Caddy logs
journalctl -u caddy -f
```

### Manual Operations

```bash
# Restart gallery service
systemctl restart sigvild-gallery

# Reload Caddy configuration
systemctl reload caddy

# Check API health
curl https://api.sigvild.no/api/health
```

## Troubleshooting

### Build Issues

**Problem**: Go build fails
```bash
# Ensure Go is installed locally
go version

# Check if you're in the right directory
ls sigvild-gallery/main.go
```

**Problem**: Frontend build fails  
```bash
# Check Node.js and npm
node --version && npm --version

# Ensure dependencies are installed
cd sigvild-gallery/sigvild-kit
npm install
```

### Service Issues

**Problem**: Service won't start
```bash
# Check service status
systemctl status sigvild-gallery

# Check service logs
journalctl -u sigvild-gallery --no-pager

# Verify binary permissions
ls -la /opt/sigvild-gallery/sigvild-gallery-server
```

**Problem**: Database permissions
```bash
# Check data directory ownership
ls -la /opt/sigvild-gallery/data/

# Fix ownership if needed
sudo chown -R sigvild:sigvild /opt/sigvild-gallery/
```

### Network Issues

**Problem**: Domain not resolving
```bash
# Test DNS resolution
dig sigvild.no
dig api.sigvild.no

# Test local connectivity
curl -H "Host: sigvild.no" http://localhost
curl -H "Host: api.sigvild.no" http://localhost
```

**Problem**: HTTPS certificate issues
```bash
# Check Caddy logs for ACME errors
journalctl -u caddy | grep -i "acme\|certificate"

# Verify DNS challenge credentials
# (Check Cloudflare API token in vault)
```

## Security Features

### Environment Protection
- **No .env files**: Secrets stored in systemd environment variables only
- **Vault encryption**: All passwords encrypted with ansible-vault
- **Memory isolation**: Secrets only exist in process memory

### SystemD Sandboxing
- **Read-only filesystem**: Application cannot modify system files
- **Isolated temporary**: Private /tmp directory
- **Limited capabilities**: No privilege escalation possible
- **Data directory only**: Write access restricted to /opt/sigvild-gallery/data/

### Web Security
- **Automatic HTTPS**: Let's Encrypt certificates via DNS challenge
- **Security headers**: XSS protection, frame options, content type sniffing prevention
- **CORS restrictions**: API access limited to frontend domain
- **Rate limiting**: API endpoint protection

## File Locations

### Application Files
- **Binary**: `/opt/sigvild-gallery/sigvild-gallery-server`
- **Database**: `/opt/sigvild-gallery/data/data.db`
- **File uploads**: `/opt/sigvild-gallery/data/storage/`
- **Frontend**: `/var/www/sigvild-gallery/`

### Configuration Files  
- **Service**: `/etc/systemd/system/sigvild-gallery.service`
- **Caddy frontend**: `/etc/caddy/sites-enabled/sigvild-frontend.caddy`
- **Caddy API**: `/etc/caddy/sites-enabled/sigvild-api.caddy`

### Log Files
- **Service logs**: `journalctl -u sigvild-gallery`
- **Caddy logs**: `journalctl -u caddy`
- **Access logs**: `/var/log/caddy/sigvild-*.log`

## Next Steps After Deployment

1. **Verify services**: Check that both domains are accessible
2. **Test authentication**: Login with host/guest credentials
3. **Upload test photo**: Verify file upload functionality
4. **Monitor logs**: Watch for any errors in service logs
5. **Backup setup**: Configure regular database backups

## Development Workflow

For ongoing development:

```bash
# 1. Make changes to sigvild-gallery project
cd ../sigvild-gallery

# 2. Test locally  
go run . serve &
cd sigvild-kit && npm run dev

# 3. Deploy updates
cd ../rick-infra
ansible-playbook site.yml --tags="sigvild"
```

The deployment system builds locally and transfers assets, so you don't need build tools on the server.