Skip to content

Installation Guide#

Not a developer? If you don't have a technical setup, you can request a Network directly at helpbuttons.org — the team can set it up for you on their server. You can also ask for help in the community Telegram group.

Helpbuttons lives in a single monorepo: github.com/helpbuttons/helpbuttons. It contains the frontend (web/), the backend API (api/), and the database configuration — all run together via Docker Compose.

Production: run with Docker#

This is the recommended way for self-hosting.

Requirements#

Steps#

1. Clone the repository

git clone https://github.com/helpbuttons/helpbuttons.git
cd helpbuttons

2. Configure your environment

cp env.sample .env

Edit .env with your settings. The key variables:

hostName=example.com          # your domain or IP
POSTGRES_PASSWORD=changeme    # set a strong password
smtpHost=                     # SMTP server for email notifications
smtpPort=
smtpUser=
smtpPass=
from=                         # sender email address

3. Generate a JWT secret

docker-compose run api yarn cli config:genjwt

Copy the generated value and add it to your .env:

jwtSecret=<paste here>

4. Start the application

docker-compose up -d

5. Run database migrations

docker-compose run api yarn migration:run

Open http://localhost:3000 in your browser. The first time you visit, a setup wizard will guide you through creating the coordinator account and your first Network.

Upgrade#

docker-compose pull
docker-compose up -d
docker-compose run api yarn migration:run

Development setup#

For contributing code, choose the mode that matches what you are working on.

Requirements#

  • Docker >= 24.0.7 and docker-compose >= 2.23.3
  • Node.js >= v20.11.0
  • Yarn >= 1.22.21
git clone https://github.com/helpbuttons/helpbuttons.git
cd helpbuttons
git checkout dev
cp env.sample .env

Edit .env with:

hostName=localhost
VERSION=dev
API_URL=http://localhost:3001/

Generate and add the JWT secret (same as production step 3 above).

Option A — work on the frontend (API + DB in Docker)#

Use this when you are changing React/Next.js code in web/.

1. In docker-compose.yml, uncomment the port exposure for api:

ports:
  - "3001:3001"

2. Start the API and database:

docker-compose up api db redis -d
docker-compose run api yarn migration:run

3. Run the frontend locally:

cd web
ln -s ../.env .
yarn
yarn dev

Browse to http://localhost:3000.

Option B — work on the backend (DB in Docker)#

Use this when you are changing NestJS code in api/.

1. In docker-compose.yml, uncomment the port exposure for db:

ports:
  - "5432:5432"

2. Start only the database:

docker-compose up db redis -d

3. Set these additional env vars in .env:

POSTGRES_HOSTNAME=localhost

4. Run the API locally:

cd api
mkdir -p uploads && chmod o+w uploads
ln -s ../.env .
yarn
yarn dev
yarn migration:run

API runs at http://localhost:3001.

Troubleshooting#

OpenSSL error on Node.js 17+

export NODE_OPTIONS=--openssl-legacy-provider

Backend fails to start due to database errors

Reset the database volume:

docker-compose down
rm -rf db/
docker-compose up -d
docker-compose run api yarn migration:run

Drop schema and restart fresh

docker-compose exec api yarn schema:drop
docker-compose run api yarn migration:run

Access the database directly

docker-compose exec db psql -U postgres hb-db

Database backup and restore

# backup
docker-compose exec db pg_dump -U postgres hb-db > dump.sql

# restore
docker exec -i <container_id> psql -U postgres hb-db < dump.sql

Preview all UI components#

Once running in dev mode, visit http://localhost:3000/RepositoryPage to browse all styled components and UI elements.

Welcome to the contributors list!#

Now head to Contributing Guide to understand the git workflow and coding conventions before submitting your first PR.