This guide describes how to set up your local development environment for contributing to Pangolin. We recommend using Docker Compose for the most consistent development experience across different environments.

​
Prerequisites

  • Text Editor (VSCode, Neovim, etc.)
  • NodeJS v20.10.0
  • NPM v10.2.3 (or similar)
  • Go v1.23.1
  • Git
  • Docker & Docker Compose
For managing multiple versions of Go, you may want to use gvm. For managing multiple versions of NodeJS, you may want to use nvm.

​
Setup Your Repository

Below is an example if you’re working on the Pangolin repository.
1

Fork and clone

Fork the repository(ies) to your own GitHub account and clone to your local device:
git clone https://github.com/YOUR_USERNAME/pangolin.git
cd pangolin/
2

Add upstream remote

Add the remote upstream:
git remote add upstream https://github.com/fosrl/pangolin.git
3

Create feature branch

Create a new branch:
git checkout -b BRANCH_NAME dev
It is recommended to give your branch a meaningful name, relevant to the feature or fix you are working on.Good examples:
  • docs-docker
  • feature-new-system
  • fix-title-cards
Bad examples:
  • bug
  • docs
  • feature
  • fix
  • patch
4

Open pull request

If you open a pull request, open it against the dev branch of the original repository.

​
Pangolin Development Setup

Choose your preferred development approach. We strongly recommend Docker Compose for the most consistent experience across all platforms.

Advantages

  • Consistent environment
  • Easy setup and teardown
  • Isolated dependencies
  • Works on any OS

Requirements

  • Docker installed
  • Docker Compose installed
  • 4GB+ RAM available
1

Install dependencies

Install package dependencies:
npm install
2

Configure environment

Ensure you have a config/ directory at the root with a config.yml inside. Refer to the Pangolin Configuration docs or the config.example.yml in the repo for a sample of what to include in that file.
You may need to tweak this to run in dev, such as setting the dashboard_url to http://localhost:3002.
3

Generate database schema

Generate the database schema and push it:
npm run db:sqlite:generate
npm run db:sqlite:push
4

Start development server

Start the development server using Docker Compose:
docker compose up --build
This will build and start all services in development mode with hot reloading enabled.
When running Pangolin for the first time there will be no exit nodes. This means that there have been no Gerbil “exit nodes” registered in the database. When Gerbil first starts up and requests its config from Pangolin for the first time it gets registered as an exit node.The easiest way to resolve this is to run Gerbil and have it register in your dev environment. Download the Gerbil binary and run it with localhost:
./gerbil \
--reachableAt=http://gerbil:3003 \
--generateAndSaveKeyTo=/var/config/key \
--remoteConfig=http://pangolin:3001/api/v1/

​
Option 2: Local Development

Local development requires more setup and may have environment-specific issues. Docker Compose is recommended for consistency.
1

Install dependencies

Install package dependencies:
npm install
2

Configure environment

Ensure you have a config/ directory at the root with a config.yml inside. Refer to the Pangolin Configuration docs or the config.example.yml in the repo for a sample of what to include in that file.
You may need to tweak this to run in dev, such as setting the dashboard_url to http://localhost:3002.
3

Generate database schema

Generate the database schema and push it:
npm run db:sqlite:generate
npm run db:sqlite:push
4

Start development server

Start the development server:
npm run dev

​
Windows Development Considerations

Windows users with Docker Desktop + WSL2: File change detection may not work properly when project files are stored on the Windows filesystem.

​
Component Development

​
Gerbil

Requirements

  • Go v1.23.1
make local

​
Newt

Requirements

  • Go v1.23.1
make local

​
Olm

Requirements

  • Go v1.23.1
make local