Skip to main content

​
Overview

Consensus can be deployed in several ways depending on your needs:
  • Local installation: Full control for development and testing
  • Docker: Containerized deployment for production
  • GitHub Codespaces: Zero-install browser-based environment

​
Prerequisites

  • Node.js 22 or later (download)
  • Yarn package manager
  • Git

​
Local installation

1

Install Node.js and Yarn

Download and install Node.js 22+ from nodejs.org.Then install Yarn globally:
npm install -g yarn
Verify your installation:
node --version  # Should be v22.x.x or higher
yarn --version
2

Clone the repository

git clone <repository-url>
cd consensus-voting-system
3

Install dependencies

Consensus uses several native dependencies that require compilation:
yarn install
This installs packages including:
  • better-sqlite3 (database)
  • bcrypt (password hashing)
  • fastify (web framework)
  • ejs (templating)
{
  "dependencies": {
    "@fastify/cookie": "^11.0.2",
    "@fastify/session": "^11.1.1",
    "@fastify/view": "^11.1.1",
    "bcrypt": "^5.1.1",
    "better-sqlite3": "^12.6.2",
    "ejs": "^4.0.1",
    "fastify": "^5.7.4"
  }
}
4

Build the project

Compile TypeScript to JavaScript:
yarn build
This creates the dist/ directory with compiled bundles.
5

Seed the database (optional)

Populate with sample data for testing:
yarn db:seed
This creates:
  • 1 admin user (admin / admin123)
  • 2 approved voters
  • 3 active elections with candidates
Skip this step if you want to start with an empty system.
6

Start the server

yarn start
The application will be available at http://localhost:3000.
import { startServer } from "./web/server";

// Log environment for debugging
console.log(`[Server] Starting with NODE_ENV=${process.env.NODE_ENV}`);

// Start the server
startServer();

​
Development mode

For development with automatic reloading: 
yarn dev
This uses nodemon to watch for changes and rebuild automatically.

​
Docker installation

Run Consensus in a containerized environment using the provided Dockerfile.
1

Build the Docker image

docker build -t consensus-voting:latest .
The Dockerfile uses a multi-stage build:
# Build stage
FROM node:22-alpine AS builder

WORKDIR /app

# Install build dependencies for native modules (bcrypt, better-sqlite3)
RUN apk add --no-cache python3 make g++

# Enable corepack for Yarn 4
RUN corepack enable && corepack prepare yarn@4 --activate

# Copy package files
COPY package.json yarn.lock ./

# Configure Yarn to use node_modules and install deps
ENV PUPPETEER_SKIP_DOWNLOAD=true
RUN yarn config set nodeLinker node-modules && \
    yarn config set enableGlobalCache false && \
    yarn install

# Copy source code
COPY tsconfig.json build.js ./
COPY src ./src

# Build the application
RUN yarn build
2

Run the container

docker run -d \
  --name consensus \
  -p 3000:3000 \
  -v consensus-data:/app/data \
  consensus-voting:latest
Options explained:
  • -d: Run in detached mode
  • --name consensus: Container name
  • -p 3000:3000: Map port 3000
  • -v consensus-data:/app/data: Persist database
3

View logs

docker logs -f consensus
You’ll see the server startup output including any created admin credentials.
4

Access the application

Navigate to http://localhost:3000 in your browser.

​
Docker Compose

For easier management, create a docker-compose.yml:
docker-compose.yml
version: '3.8'

services:
  consensus:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - consensus-data:/app/data
    environment:
      - NODE_ENV=production
      - PORT=3000
    restart: unless-stopped

volumes:
  consensus-data:
Then start with: 
docker-compose up -d

​
GitHub Codespaces

Run Consensus entirely in your browser without any local installation.
1

Create a Codespace

  1. Navigate to the GitHub repository
  2. Click the Code button
  3. Select the Codespaces tab
  4. Click Create codespace on master
The dev container will automatically install Node.js 22 and all dependencies. This may take a few minutes on first launch.
2

Wait for setup

The Codespace will automatically:
  • Install Node.js and Yarn
  • Run yarn install
  • Configure the development environment
You can monitor progress in the terminal.
3

Start the server

Once setup completes, run:
yarn start
Codespaces will automatically forward port 3000 and prompt you to open the application.
4

Access the application

Click “Open in Browser” when prompted, or:
  1. Go to the Ports tab
  2. Find port 3000
  3. Click the globe icon to open in browser
When using Codespaces, login credentials will be printed to the terminal on first startup. Make note of them as they won’t be shown again.

​
Environment configuration

Customize Consensus behavior using environment variables:
.env (example)
# Server configuration
PORT=3000
HOST=0.0.0.0
NODE_ENV=production

# Database
DATA_DIR=/app/data

# Session security (change in production!)
SESSION_SECRET=your-secure-random-string-here

# Admin default password (only used if no admin exists)
CONSENSUS_ADMIN_DEFAULT_PASSWORD=admin123
Always change the default session secret and admin password in production environments.

​
Database management

​
Reset database

To clear all data and start fresh: 
yarn db:reset
This permanently deletes all elections, voters, votes, and admin accounts.

​
Backup database

The SQLite database is stored at:
  • Local: {DATA_DIR}/consensus.db (default: OS-specific data directory)
  • Docker: /app/data/consensus.db (persisted in named volume)
Create a backup: 
# Local
cp "$(yarn node -e 'console.log(require(\"./dist/db/connection\").DatabaseConnection.DB_PATH)')" backup.db

# Docker
docker cp consensus:/app/data/consensus.db backup.db

​
Troubleshooting

Some dependencies (bcrypt, better-sqlite3) require native compilation.On Linux/macOS:
# Install build tools
# Ubuntu/Debian
sudo apt-get install build-essential python3

# macOS
xcode-select --install
On Windows:
  • Install Visual Studio Build Tools
  • Or use Docker instead
Change the port via environment variable:
PORT=8080 yarn start
Or modify src/config.ts directly.
Check logs for errors:
docker logs consensus
Common issues:
  • Missing data volume mount
  • Insufficient permissions
  • Port conflict
Manually configure port forwarding:
  1. Open the Ports panel
  2. Click Forward a Port
  3. Enter 3000
  4. Set visibility to Public if needed

​
What’s next?

Quick Start

Learn how to use Consensus from a voter’s perspective

Admin Guide

Learn how to manage elections and voters

Build docs developers (and LLMs) love

Get started for freeTalk to us