Set up a development machine
This page gets the Foxden code building and tested on your own computer, on macOS, Linux or Windows, so you can change an app and check your change before you open a pull request.
Before you start
You need:
- Git.
- Node.js 22 with npm. Arctic uses pnpm, which Node's
corepackprovides: runcorepack enableonce. - Bun, only to work on the
foxdencommand line (tools/foxden). - Docker with Compose v2, to run the demo and a local Postgres.
- A Bash shell. The scripts are Bash and run on macOS, Linux, and Windows with WSL or Git Bash.
On Windows, WSL is the simplest path. The repository contains symbolic links (each app reaches the shared code through one), so with Git Bash, clone with symbolic links turned on:
git clone -c core.symlinks=true <repository address>Install an app and the shared code
Each app has its own dependencies and lockfile, and so does packages/shared, which every app uses. Install both at once with the bootstrap script, from the repository's top folder:
scripts/bootstrap.sh libraryThe names the scripts take:
| Name | What it installs |
|---|---|
admin | Foxden Admin (products/admin/apps/auth) |
crm | Fennec (products/crm) |
arctic | Arctic, with its notetaker service |
corsac, pampas, cape, library | The app of that name |
communications | Culpeo (products/communications) |
shared, brand, updater | The shared packages |
foxden | The command line (tools/foxden) |
docs | This site (docs/portal) |
You can name several apps at once, use --changed for whatever your branch touches, or --all for everything (this takes several minutes).
If an app's tests fail to start with Cannot find module 'zod' (or another module) inside packages/shared, the shared code was not installed. Run scripts/bootstrap.sh for the app again rather than changing the shared code.
Run the whole suite with demo data
The demo builds every app from your checkout, starts them in Docker with a fictional company's data, and prints how to sign in. It needs no keys, no domain and no Google client.
Start the demo:
bashscripts/demo.sh upThe first run builds every image and takes a while. When the apps are ready, it prints a one-time sign-in link for Admin and each app's address (ports 3110 to 3118).
Open the sign-in link. It signs you in to Admin.
Open any app's address. Admin's sign-in carries you in.
Stop the demo with
scripts/demo.sh down. Your demo data stays for the nextup;scripts/demo.sh resetdeletes it and starts again.
In the demo, AI and email are off, Cape places and takes no calls, and Arctic's notetaker joins no real meeting. To run a second demo beside the first, set DEMO_PROJECT and DEMO_PORT_OFFSET, for example DEMO_PROJECT=foxden-demo-2 DEMO_PORT_OFFSET=100 scripts/demo.sh up.
Run one app from source
To work on one app with fast reloads, run it with its development server against a local Postgres 17.
Start a Postgres 17 database, for example in Docker.
In the app's folder, copy its example environment file to
.env:App Example file Admin, Fennec, Arctic, Pampas, Culpeo .env.exampleCorsac .env.production.exampleCape, Library .env.prod.exampleFill in what the file marks as required. It names every setting the app reads; every app needs at least a database address (
DATABASE_URL) and a secret.Apply the app's database migrations. Most migration scripts read
DATABASE_URLfrom the environment, not from the file:bashDATABASE_URL=postgres://<user>:<password>@localhost:5432/<database> npm run db:migrateStart the development server with
npm run dev(pnpm devfor Arctic). Library listens on port 3480; the others on Next.js's default port, 3000, unless you set another.
An app running alone has no AI and its own sign-in. To see an app connected to Admin, use the demo.
Check your change
scripts/verify.sh runs the typecheck and unit tests for whatever your branch changed, compared with origin/main:
scripts/verify.sh # everything your branch touches
scripts/verify.sh library # one app
scripts/verify.sh --list # only say what would runIt ends with verify: green and the names it checked, or names each one that is red. It runs only on your machine; the pull request's checks run the same scripts again. See Make a change and open a pull request.
Database tests
Admin, Fennec, Corsac, Pampas, Culpeo, Cape and Library also have database tests. They delete what they find, so point them only at a throwaway Postgres 17 database on your own machine, with a name that marks it as a test database (foxden_test, for example). Most apps refuse any other.
Apply the app's migrations to the test database:
bashDATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/foxden_test npm run db:migrateRun the tests with the database's address in the variable the app reads:
bashTEST_DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/foxden_test npm run test:integrationApp Variable Admin, Fennec TEST_DATABASE_URLCorsac, Pampas, Cape, Library DATABASE_URLCulpeo COMMUNICATIONS_TEST_DATABASE_URL
Troubleshooting
verify.sh says nothing changed
It compares your branch with origin/main. Fetch first (git fetch origin), or name the app: scripts/verify.sh library.
A test is skipped on your machine
Some tests need Linux (a file under /proc, or a tool the Linux checks carry), and skip themselves elsewhere. The pull request's checks run on Linux and run them.