Skip to content

Guide for IT Departments

Jump to bottom
femi345 edited this page Jun 30, 2026 · 6 revisions

OpenBook Guide for IT Departments

This guide is for the person setting up OpenBook for their town. You should be comfortable with a command line. Setup takes a few hours.

OpenBook is a Node.js web app with a Postgres database. Your job is to get the app running, connect it to Postgres, point a web address at it, and hand the login to your town manager.

What You Need

  • Node.js 20 LTS or later
  • npm 9+
  • A Postgres database connection string

For testing, a free Postgres database from Vercel Storage, Neon, or Supabase is enough.

If your database provider gives you both a pooled connection string and a direct connection string, use:

Variable Value
DATABASE_URL Pooled/runtime Postgres connection string
DIRECT_URL Direct Postgres connection string, if available

Path A — Deploy with Vercel

Use this if you want Vercel to handle hosting, builds, HTTPS, and custom domains.

A1. Fork the repository

Go to github.com/Allen-Lab-for-Democracy-Renovation/Open-Book and click Fork to copy it to your town's GitHub account or your own account.

A2. Create a Postgres database

Create a Postgres database through Vercel Storage, Neon, Supabase, or another managed Postgres provider.

Copy the Postgres connection string. It usually starts with postgresql://.

A3. Connect to Vercel

  1. Create a free account at vercel.com.
  2. Click Add New Project and import your forked repository.
  3. Vercel detects it as a Next.js project automatically.
  4. Before deploying, add environment variables:
Variable Required Description
DATABASE_URL Yes Postgres connection string used by the running app
DIRECT_URL No Direct Postgres connection string for migrations when using pooled databases
  1. Click Deploy.

Vercel builds the app, applies database migrations, and gives you a live URL like openbook-abc123.vercel.app.

A4. Set up your domain

Right now your portal is at a Vercel URL like openbook-abc123.vercel.app. This step connects a real non-Vercel address like budget.yourtown.gov so residents and your town manager see something recognizable.

First, add the domain in Vercel:

In your Vercel project, go to Settings → Domains → Add Domain. Type the full address you want residents to use, such as budget.yourtown.gov, and click Add.

Then, create a DNS record so the address points to Vercel:

Go to wherever your town manages DNS records and add a new record:

Field What to enter
Type CNAME
Name or Host Just the subdomain part, such as budget
Value or Points to cname.vercel-dns.com

Once the DNS record is live, Vercel detects it and issues an HTTPS certificate automatically.

If your town does not manage its own DNS, ask your website vendor to create the CNAME record for you.

Tip: Municipal governments can register .gov domains for free at get.gov.

A5. Create the admin account

Go to https://your-domain/admin/register. Enter a name, email, and password. Click Create Account.

This page locks after the first account is created. Hand the login credentials to your town manager.

A6. Applying updates

If you forked the repository, pull updates from the upstream repo and push to your fork. Vercel redeploys automatically.

Path B — Self-Hosted Server

Use this if your town has a Linux or Windows server that can run Node.js 20+ and can connect to Postgres.

B1. Install Node.js

Install Node.js 20 LTS from nodejs.org. Verify with:

node --version
npm --version

B2. Create or choose a Postgres database

Create a Postgres database on your server or through a managed provider such as Neon or Supabase.

Copy the connection string. It usually starts with postgresql://.

B3. Get the code

git clone https://github.com/Allen-Lab-for-Democracy-Renovation/Open-Book.git
cd Open-Book

B4. Configure environment variables

cp .env.example .env.local

Edit .env.local and set:

DATABASE_URL="postgresql://user:password@host:5432/openbook?sslmode=require"
DIRECT_URL="postgresql://user:password@host:5432/openbook?sslmode=require"

If your provider only gives one connection string, set DATABASE_URL and leave DIRECT_URL unset.

B5. Install and build

npm install
npm run build

The build step applies database migrations to the configured Postgres database.

B6. Start the app

npm install -g pm2
pm2 start "npm start" --name openbook
pm2 save
pm2 startup

The app runs on port 3000. Verify at http://your-server-ip:3000.

B7. Set up your domain

Create a subdomain like budget.yourtown.gov:

  1. In your DNS provider, add an A record pointing to your server's IP.
  2. Set up a reverse proxy, such as nginx, to forward port 80/443 to port 3000.
  3. Use Certbot for a free SSL certificate.

If your website is managed by CivicPlus, Granicus, Revize, or another vendor, ask them to create the DNS record for you.

Tip: Municipal governments can register .gov domains for free at get.gov.

server {
    listen 80;
    server_name budget.yourtown.gov;
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
    }
}
sudo certbot --nginx -d budget.yourtown.gov

B8. Create the admin account

Go to https://budget.yourtown.gov/admin/register. Enter a name, email, and password. Click Create Account.

This page locks after the first account is created. Hand the login credentials to your town manager.

B9. Applying updates

git pull origin main
npm install
npm run build
pm2 restart openbook

Database migrations run during the build.

After Setup

Hand off to your town manager

Give them:

  • The portal URL, such as https://budget.yourtown.gov
  • The admin login URL, such as https://budget.yourtown.gov/admin/login
  • The admin email and password

Point them to the Guide for Town Managers. Your involvement from here is minimal unless the server goes down, the database needs maintenance, DNS changes, or code updates need to be applied.

Staff user management

If your town uses the capital request feature, the admin can invite department staff from the Users tab. Staff get a single-use invite link, click it, and create their account. The admin can also restrict invites to specific email domains, such as yourtown.gov, and generate password reset links.

Backups

Back up the Postgres database using your database provider's backup tools. For testing databases, enable scheduled backups if the provider supports them.

Security

  • Passwords hashed with scrypt, never stored in plaintext
  • HTTP-only session cookies, 7-day expiry
  • Staff registration requires a single-use admin-issued invite token
  • Run the app behind HTTPS
  • Restrict staff invites to your town's email domain when possible

Troubleshooting

Stuck creating the first admin account: confirm DATABASE_URL is set in the deployment environment, redeploy or restart the app, and check the build/runtime logs for migration or database connection errors.

Migration errors with Neon, Supabase, or another pooled database: set DIRECT_URL using the provider's direct connection string, then redeploy or rerun npm run build.

No tables exist in the database: run npx prisma migrate deploy with DATABASE_URL set, or redeploy after adding environment variables.

Staff member can't log in: Check the Users tab. Create a new invite or click Reset Password.

Transfer admin access: Done from the admin panel's Transfer tab.

Clone this wiki locally