Skip to content
GuideForDeveloperWith or without Foxden Admin

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 corepack provides: run corepack enable once.
  • Bun, only to work on the foxden command 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:

bash
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:

bash
scripts/bootstrap.sh library

The names the scripts take:

NameWhat it installs
adminFoxden Admin (products/admin/apps/auth)
crmFennec (products/crm)
arcticArctic, with its notetaker service
corsac, pampas, cape, libraryThe app of that name
communicationsCulpeo (products/communications)
shared, brand, updaterThe shared packages
foxdenThe command line (tools/foxden)
docsThis 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.

  1. Start the demo:

    bash
    scripts/demo.sh up

    The 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).

  2. Open the sign-in link. It signs you in to Admin.

  3. Open any app's address. Admin's sign-in carries you in.

  4. Stop the demo with scripts/demo.sh down. Your demo data stays for the next up; scripts/demo.sh reset deletes 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.

  1. Start a Postgres 17 database, for example in Docker.

  2. In the app's folder, copy its example environment file to .env:

    AppExample file
    Admin, Fennec, Arctic, Pampas, Culpeo.env.example
    Corsac.env.production.example
    Cape, Library.env.prod.example
  3. Fill 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.

  4. Apply the app's database migrations. Most migration scripts read DATABASE_URL from the environment, not from the file:

    bash
    DATABASE_URL=postgres://<user>:<password>@localhost:5432/<database> npm run db:migrate
  5. Start the development server with npm run dev (pnpm dev for 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:

bash
scripts/verify.sh            # everything your branch touches
scripts/verify.sh library    # one app
scripts/verify.sh --list     # only say what would run

It 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.

  1. Apply the app's migrations to the test database:

    bash
    DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/foxden_test npm run db:migrate
  2. Run the tests with the database's address in the variable the app reads:

    bash
    TEST_DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/foxden_test npm run test:integration
    AppVariable
    Admin, FennecTEST_DATABASE_URL
    Corsac, Pampas, Cape, LibraryDATABASE_URL
    CulpeoCOMMUNICATIONS_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.

Foxden is open source under Apache-2.0.