--- url: https://docs.codefox.ai/contribute/development-setup.md --- # 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 ``` ## 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: | 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. 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`: | App | Example 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://:@localhost:5432/ 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](/contribute/make-a-change). ### 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 ``` | App | Variable | |---|---| | Admin, Fennec | `TEST_DATABASE_URL` | | Corsac, Pampas, Cape, Library | `DATABASE_URL` | | Culpeo | `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. ## Related * [Repository layout](/contribute/repository-tour) * [Write a docs page](/contribute/write-docs)