likwid/DEPLOYMENT.md

# Likwid Deployment Guide

Likwid supports two distinct deployment modes: **Production** and **Demo**. These are separate instances with their own databases.

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                        PRODUCTION                                │
│  ┌──────────┐    ┌──────────┐    ┌──────────────────────┐       │
│  │ Frontend │───▶│ Backend  │───▶│ PostgreSQL (prod_db) │       │
│  │  :4321   │    │  :3000   │    │       :5432          │       │
│  └──────────┘    └──────────┘    └──────────────────────┘       │
│  DEMO_MODE=false │ No demo data │ Clean database                │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                          DEMO                                    │
│  ┌──────────┐    ┌──────────┐    ┌──────────────────────┐       │
│  │ Frontend │───▶│ Backend  │───▶│ PostgreSQL (demo_db) │       │
│  │  :4322   │    │  :3001   │    │       :5433          │       │
│  └──────────┘    └──────────┘    └──────────────────────┘       │
│  DEMO_MODE=true  │ Seed data    │ Resettable database           │
└─────────────────────────────────────────────────────────────────┘
```

## Quick Start

### Production Deployment

```bash
# 1. Copy and configure environment
cp compose/.env.production.example compose/.env.production

# 2. Edit .env.production with secure values
#    - Set strong POSTGRES_PASSWORD
#    - Set random JWT_SECRET (64+ chars)
#    - Set your domain in API_BASE

# 3. Ensure demo seed data is excluded
#    - Demo seed migrations live in backend/migrations_demo
#    - backend/src/main.rs only runs migrations_demo when DEMO_MODE=true
#    - compose/production.yml builds the backend with INCLUDE_DEMO_SEED=false

# 4. Deploy
cd compose
podman compose --env-file .env.production -f production.yml up -d

# 5. Access at http://localhost:4321
```

### Demo Deployment

```bash
# 1. Copy environment (defaults are fine for demo)
cp compose/.env.demo.example compose/.env.demo

# 2. Deploy
cd compose
podman compose --env-file .env.demo -f demo.yml up -d

# 3. Access at http://localhost:4322
```

For VPS deployments, it is recommended to bind demo ports to localhost and put a reverse proxy (TLS) in front.

- Set `BACKEND_BIND_HOST=127.0.0.1` and `FRONTEND_BIND_HOST=127.0.0.1` in `compose/.env.demo`
- Point `API_BASE` at your public domain (for example `https://openlikwid.org`)
- Serve the demo via the reverse proxy on `80/443`

## Start on boot (systemd --user)

This repo includes `systemd --user` unit templates:

- `systemd/likwid-demo.service`
- `systemd/likwid-prod.service`

These units assume the repo is checked out at `~/likwid` for the target user, and they run `podman compose` using the env files under `compose/`.

## Smoke test

An operator smoke test script is provided:

- `scripts/smoke-test.sh demo`
- `scripts/smoke-test.sh prod`

## Demo Instance Details

### Demo Accounts

| Username    | Password | Role                        |
|-------------|----------|------------------------------|
| contributor | demo123  | Standard member              |
| moderator   | demo123  | Can moderate content         |
| observer    | demo123  | Read-only access             |

### Pre-seeded Data

- **3 Communities**
  - Aurora Framework (tech/OSS governance)
  - Civic Commons Network (civic engagement)
  - Regional Makers Collective (federated makerspaces)

- **13 Users** with realistic profiles

- **7 Proposals** in various states (draft, discussion, voting, closed)

- **Delegation relationships** demonstrating liquid democracy

- **Moderation history** showing governance in action

### Resetting Demo

To reset the demo to a clean state:

```bash
# Windows
.\scripts\demo-reset.ps1

# Linux/macOS
./scripts/demo-reset.sh

# Or manually:
podman compose --env-file compose/.env.demo -f compose/demo.yml down -v
podman compose --env-file compose/.env.demo -f compose/demo.yml up -d
```

## Configuration Reference

### Environment Variables

| Variable          | Production Default | Demo Default              | Description                    |
|-------------------|-------------------|---------------------------|--------------------------------|
| POSTGRES_USER     | likwid            | likwid_demo               | Database username              |
| POSTGRES_PASSWORD | (required)        | demo_secret_change_me     | Database password              |
| POSTGRES_DB       | likwid_prod       | likwid_demo               | Database name                  |
| DB_PORT           | 5432              | 5433                      | Database port                  |
| JWT_SECRET        | (required)        | demo_jwt_secret_...       | JWT signing secret             |
| BACKEND_PORT      | 3000              | 3001                      | Backend API port               |
| BACKEND_BIND_HOST | 0.0.0.0           | 0.0.0.0                   | Backend bind host for published port (set to `127.0.0.1` on VPS) |
| FRONTEND_PORT     | 4321              | 4322                      | Frontend port                  |
| FRONTEND_BIND_HOST| 0.0.0.0           | 0.0.0.0                   | Frontend bind host for published port (set to `127.0.0.1` on VPS) |
| API_BASE          | (your domain)     | http://localhost:3001     | Public API URL                 |
| DEMO_MODE         | false             | true                      | Enable demo features           |

### Demo Mode Features

When `DEMO_MODE=true`:
- Demo accounts are recognized and can log in
- Destructive actions on demo data are restricted
- Reset endpoint available at `/api/demo/reset` (admin only)
- Demo status shown at `/api/demo/status`

## Development Setup

For local development without containers:

```bash
# 1. Start only the database
podman compose -f compose/dev.yml up -d

# 2. Configure backend environment
cp backend/.env.example backend/.env

# 3. Run backend natively
cd backend
cargo run

# 4. Run frontend natively
cd frontend
npm run dev
```

## Monitoring & Logs

```bash
# View all logs
podman compose --env-file compose/.env.demo -f compose/demo.yml logs -f

# View specific service
podman compose --env-file compose/.env.demo -f compose/demo.yml logs -f backend

# Check health
curl http://localhost:3001/health
```

## Troubleshooting

### Database connection issues
```bash
# Check if postgres is running
podman compose --env-file compose/.env.demo -f compose/demo.yml ps

# View postgres logs
podman compose --env-file compose/.env.demo -f compose/demo.yml logs postgres
```

### Migration failures
```bash
# Connect to database and check
podman exec -it likwid-demo-db psql -U likwid_demo -d likwid_demo

# List tables
\dt

# Check migration status
SELECT * FROM _sqlx_migrations;
```

### Reset everything
```bash
# Nuclear option - removes all data and volumes
podman compose --env-file compose/.env.demo -f compose/demo.yml down -v
podman compose --env-file compose/.env.demo -f compose/demo.yml up -d
```