--- title: "Development Guide" description: "Set up your local development environment for contributing to Pangolin" --- 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](https://github.com/moovweb/gvm). For managing multiple versions of NodeJS, you may want to use [nvm](https://github.com/nvm-sh/nvm). ## Setup Your Repository Below is an example if you're working on the Pangolin repository. [Fork](https://help.github.com/articles/fork-a-repo/) the repository(ies) to your own GitHub account and [clone](https://help.github.com/articles/cloning-a-repository/) to your local device: ```bash git clone https://github.com/YOUR_USERNAME/pangolin.git cd pangolin/ ``` Add the remote `upstream`: ```bash git remote add upstream https://github.com/fosrl/pangolin.git ``` Create a new branch: ```bash 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` If you open a pull request, open it against the `dev` branch of the original repository. ## Pangolin Development Setup ### Option 1: Docker Compose (Recommended) - Consistent environment - Easy setup and teardown - Isolated dependencies - Works on any OS - Docker installed - Docker Compose installed - 4GB+ RAM available Install package dependencies: ```bash npm install ``` Ensure you have a `config/` directory at the root with a `config.yml` inside. Refer to the [Pangolin Configuration docs](/self-host/advanced/config-file) 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`. Generate the database schema and push it: ```bash npm run db:sqlite:generate npm run db:sqlite:push ``` Start the development server using Docker Compose: ```bash 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: ```bash ./gerbil \ --remoteConfig http://localhost:3001/api/v1/gerbil/get-config \ --reportBandwidthTo http://localhost:3001/api/v1/gerbil/receive-bandwidth \ --generateAndSaveKeyTo=/var/key \ --reachableAt=http://localhost:3003 ``` ### Option 2: Local Development Local development requires more setup and may have environment-specific issues. Docker Compose is recommended for consistency. Install package dependencies: ```bash npm install ``` Ensure you have a `config/` directory at the root with a `config.yml` inside. Refer to the [Pangolin Configuration docs](/self-host/advanced/config-file) 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`. Generate the database schema and push it: ```bash npm run db:sqlite:generate npm run db:sqlite:push ``` Start the development server: ```bash npm run dev ``` ## Component Development ### Gerbil - Go v1.23.1 ```bash make local ``` ### Newt - Go v1.23.1 ```bash make local ``` ### Olm - Go v1.23.1 ```bash make local ```