From 5fd905c9b766e09d048e700c148f15abbeee250b Mon Sep 17 00:00:00 2001 From: Marco Allegretti Date: Thu, 29 Jan 2026 00:48:14 +0100 Subject: [PATCH] docs: update README and deployment workflow --- CONTRIBUTING.md | 4 ++-- DEPLOYMENT.md | 31 +++++++++++++++++-------------- README.md | 8 ++++---- WORKFLOW.md | 47 +++++++++++++++++++++++++---------------------- 4 files changed, 48 insertions(+), 42 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 12d873e..98ddc09 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,7 +28,7 @@ git clone https://codeberg.org/likwid/likwid cd likwid # Copy environment configuration -cp .env.example .env +cp backend/.env.example backend/.env # Start development environment # Windows: @@ -203,6 +203,6 @@ Help newcomers, answer questions patiently, and remember that everyone was new o ## License -By contributing, you agree that your contributions will be licensed under LGPL-2.1-or-later. +By contributing, you agree that your contributions will be licensed under EUPL-1.2. --- diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 8b0bf8d..b96f9ce 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -37,8 +37,10 @@ cp compose/.env.production.example compose/.env.production # - Set random JWT_SECRET (64+ chars) # - Set your domain in API_BASE -# 3. Remove demo seed migration (important!) -rm backend/migrations/20260127150000_demo_seed_data.sql +# 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 @@ -97,8 +99,8 @@ To reset the demo to a clean state: ./scripts/demo-reset.sh # Or manually: -podman-compose -f compose/demo.yml down -v -podman-compose --env-file .env.demo -f compose/demo.yml up -d +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 @@ -133,12 +135,14 @@ For local development without containers: # 1. Start only the database podman-compose -f compose/dev.yml up -d -# 2. Run backend natively +# 2. Configure backend environment +cp backend/.env.example backend/.env + +# 3. Run backend natively cd backend -cp ../.env.example .env # Configure DATABASE_URL cargo run -# 3. Run frontend natively +# 4. Run frontend natively cd frontend npm run dev ``` @@ -147,10 +151,10 @@ npm run dev ```bash # View all logs -podman-compose -f compose/demo.yml logs -f +podman-compose --env-file compose/.env.demo -f compose/demo.yml logs -f # View specific service -podman-compose -f compose/demo.yml logs -f backend +podman-compose --env-file compose/.env.demo -f compose/demo.yml logs -f backend # Check health curl http://localhost:3001/health @@ -161,10 +165,10 @@ curl http://localhost:3001/health ### Database connection issues ```bash # Check if postgres is running -podman-compose -f compose/demo.yml ps +podman-compose --env-file compose/.env.demo -f compose/demo.yml ps # View postgres logs -podman-compose -f compose/demo.yml logs postgres +podman-compose --env-file compose/.env.demo -f compose/demo.yml logs postgres ``` ### Migration failures @@ -182,7 +186,6 @@ SELECT * FROM _sqlx_migrations; ### Reset everything ```bash # Nuclear option - removes all data and volumes -podman-compose -f compose/demo.yml down -v -podman volume prune -f -podman-compose -f compose/demo.yml up -d +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 ``` diff --git a/README.md b/README.md index 9e3341e..7cd13c4 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Likwid is an open-source platform for participatory governance, designed to make collective decision-making accessible, transparent, and genuinely democratic. Built for communities, civic organizations, and any group that values structured deliberation over shouting matches. -> *"We are citizens of the 21st century, but we rely on institutions designed in the 19th century. The problem is not democracy, it's the interface."* +> *"We are citizens of the 21st century, but we rely on institutions designed in the 19th century, through means designed in the 13th century. The problem is not democracy, it's the interface."* ## Philosophy @@ -33,7 +33,7 @@ Likwid implements the principles of **Democracy Design**: - **Quadratic Voting** — express intensity of preference ### Liquid Delegation -- Delegate your vote by topic or globally +- Delegate your vote globally or within a community - Real-time transparency: see how delegates vote - Revoke delegation instantly - Transitive delegation chains @@ -84,7 +84,7 @@ Likwid implements the principles of **Democracy Design**: # 1. Clone and configure git clone https://invent.kde.org/marcoa/likwid.git cd likwid -cp .env.example .env +cp backend/.env.example backend/.env # 2. Start everything (database + backend + frontend) .\scripts\dev-start.ps1 @@ -148,7 +148,7 @@ likwid/ ## License -LGPL-2.1-or-later +EUPL-1.2 ## Acknowledgments Inspired by: diff --git a/WORKFLOW.md b/WORKFLOW.md index dac731d..7b8c95b 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -25,8 +25,8 @@ ## Daily Development Workflow -### Your current setup IS the demo -Your local environment with `DEMO_MODE=true` and the seeded database is functionally equivalent to the demo deployment. +### Your local setup can behave like the demo +Your local environment is functionally equivalent to the demo deployment when `DEMO_MODE=true` and demo seed migrations have been applied (from `backend/migrations_demo`). ### Making code changes 1. Edit code normally @@ -50,6 +50,9 @@ cd backend sqlx database drop -y sqlx database create sqlx migrate run + +# If you want demo seed data, also run: +sqlx migrate run --source migrations_demo ``` ### Option 2: Use the reset script (when using containers) @@ -68,14 +71,11 @@ podman-compose --env-file compose/.env.demo -f compose/demo.yml up -d ### For real users (Production) ```bash -# 1. Remove demo seed data -rm backend/migrations/20260127150000_demo_seed_data.sql - -# 2. Configure production +# 1. Configure production cp compose/.env.production.example compose/.env.production # Edit with secure passwords and your domain -# 3. Deploy +# 2. Deploy podman-compose --env-file compose/.env.production -f compose/production.yml up -d ``` @@ -84,29 +84,32 @@ podman-compose --env-file compose/.env.production -f compose/production.yml up - ### "I broke the demo data" ```powershell cd backend -sqlx database drop -y && sqlx database create && sqlx migrate run +sqlx database drop -y +sqlx database create +sqlx migrate run ``` ### "I want to test production-like (no demo data)" ```powershell -# Temporarily move the demo migration -mv backend/migrations/20260127150000_demo_seed_data.sql backend/migrations/20260127150000_demo_seed_data.sql.bak - -# Reset database -sqlx database drop -y && sqlx database create && sqlx migrate run - # Set DEMO_MODE=false in .env + +# Reset database (core migrations only) +cd backend +sqlx database drop -y +sqlx database create +sqlx migrate run ``` ### "I want demo data back" ```powershell -# Restore migration -mv backend/migrations/20260127150000_demo_seed_data.sql.bak backend/migrations/20260127150000_demo_seed_data.sql - -# Reset database -sqlx database drop -y && sqlx database create && sqlx migrate run - # Set DEMO_MODE=true in .env + +# Reset database + re-seed demo +cd backend +sqlx database drop -y +sqlx database create +sqlx migrate run +sqlx migrate run --source migrations_demo ``` ### "I want to run both demo and production locally" @@ -120,6 +123,6 @@ Use the container deployments - they use different ports: |---------|----------| | Code changes affect demo? | Yes, same codebase. That's expected. | | Data separation | Different databases (demo vs prod) | -| Reset demo | `sqlx database drop && create && migrate` | -| Test production locally | Remove demo migration, set DEMO_MODE=false | +| Reset demo | `sqlx database drop; sqlx database create; sqlx migrate run; sqlx migrate run --source migrations_demo` | +| Test production locally | Set DEMO_MODE=false and run only core migrations (skip `migrations_demo`) | | Deploy for others | Use compose files with separate DBs |