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

# 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

# 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

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:

# 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:

# 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

# 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

# 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

# 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

# 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