Skip to main content
Get OpenCouncil up and running on your local machine in minutes. This guide covers three setup methods: Docker (recommended), manual setup, and Nix flakes.

​
Prerequisites

Node.js 18+

Required for running the Next.js application

PostgreSQL 14+

With PostGIS extension for geospatial data

Docker

Recommended for easiest setup

Nix (optional)

For reproducible development environments
The fastest way to get started is using Docker. This method automatically sets up the database, runs migrations, and seeds sample data.
1

Clone the repository

git clone https://github.com/schemalabz/opencouncil.git
cd opencouncil
2

Create environment file

cp .env.example .env
Edit .env and add your API keys. At minimum, you’ll need:
  • NEXTAUTH_SECRET - Generate with openssl rand -base64 32
  • RESEND_API_KEY - For email authentication (get from resend.com)
  • ANTHROPIC_API_KEY - For AI features (get from anthropic.com)
See the environment setup guide for all configuration options
3

Start the application

./run.sh
This script will:
  • Start PostgreSQL with PostGIS
  • Run database migrations
  • Seed the database with sample data
  • Launch the Next.js dev server
The application will be available at http://localhost:3000
4

Access the application

Open your browser and navigate to:
Sample cities and meetings are automatically seeded. Look for test users in the database for authentication.

​
Advanced Docker options

The run.sh script supports several options for different use cases:
Use your own PostgreSQL instance instead of Docker:
./run.sh --skip-db
Make sure DATABASE_URL in .env points to your database.
Build and run in production mode:
./run.sh --prod
The script automatically detects port conflicts and uses alternative ports:
  • App: 3000, 3001, 3002, …
  • Database: 5432, 5433, 5434, …
  • Prisma Studio: 5555, 5556, 5557, …
Remove all containers, volumes, and networks:
./run.sh --clean

​
Manual setup

If you prefer to run without Docker:
1

Clone and install dependencies

git clone https://github.com/schemalabz/opencouncil.git
cd opencouncil
npm install
2

Set up PostgreSQL database

You have two options:Option 1: Use Docker for database only
docker compose up db -d
Option 2: Use your own PostgreSQL instanceMake sure it has the PostGIS extension installed:
CREATE EXTENSION IF NOT EXISTS postgis;
Set the DATABASE_URL in your .env file:
DATABASE_URL="postgresql://user:password@host:port/database"
3

Run database migrations

# Run migrations
npx prisma migrate deploy

# Generate Prisma client
npx prisma generate
4

Seed the database (optional)

Load sample data for development:
npx prisma db seed
This downloads seed data from GitHub and populates your database with sample cities, meetings, and users.
5

Start the development server

npm run dev
The application will be available at http://localhost:3000

​
Nix setup

OpenCouncil supports a flake-based development environment for reproducible builds.
1

Install Nix with flakes

If you don’t have Nix installed:
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
2

Clone the repository

git clone https://github.com/schemalabz/opencouncil.git
cd opencouncil
3

Enter the Nix development shell

nix develop
This provides all dependencies (Node.js, PostgreSQL, etc.) in an isolated environment.
4

Run the development environment

nix run .#dev
This starts the full stack with process-compose, including:
  • PostgreSQL database
  • Next.js development server
  • Database migrations
Use nix run .#dev -- --help to see all available options and database modes
For detailed Nix configuration options, see the Nix deployment guide.

​
Environment variables

Create a .env file with these required variables: 
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/development"
DIRECT_URL="postgresql://postgres:postgres@localhost:5432/development"
Never commit your .env file to version control. The .env.example file contains all variable names with placeholder values.
For a complete list of environment variables, see the environment setup guide.

​
Development tools

Once running, you have access to these tools:

Prisma Studio

Visual database editor
npm run prisma:studio

Run tests

Execute test suite
npm test

Type checking

Validate TypeScript
npm run build

Linting

Check code quality
npm run lint

​
Troubleshooting

If port 3000 is already taken, the Docker script will automatically use the next available port (3001, 3002, etc.). For manual setup, change the port in package.json:
"dev": "next dev -p 3001"
Ensure PostgreSQL is running and has the PostGIS extension:
# Check if PostgreSQL is running
docker compose ps

# Or for manual setup
psql -U postgres -c "SELECT PostGIS_version();"
Reset the database and re-run migrations:
npm run prisma:migrate:reset
This will delete all data in your database
The seed script automatically downloads data from GitHub. If it fails, check your internet connection or download manually:
curl -o prisma/seed_data.json https://raw.githubusercontent.com/schemalabz/opencouncil/main/prisma/seed_data.json
Reinstall dependencies:
rm -rf node_modules package-lock.json
npm install

​
Next steps

Architecture

Learn how OpenCouncil is structured

Contributing

Join the development community

API Reference

Explore the REST API

Deployment

Deploy to production

Build docs developers (and LLMs) love

Get started for freeTalk to us