local development

info

this guide is for contributing to overlord's source code. if you're looking to use overlord, see the getting started guide.

prerequisites#

clone the repository and install dependencies:

git clone https://github.com/overlord-run/overlord.git
cd overlord
pnpm install

build the shared protocol package and server:

pnpm --filter @overlordai/protocol build
pnpm --filter @overlordai/server build

populate the database with sample developers, projects, and machines:

pnpm dev:seed

this creates the following test accounts:

username	role	password	totp secret
`admin`	admin	`test-password-123`	`JBSWY3DPEHPK3PXP`
`alice`	lead	`test-password-123`	`JBSWY3DPEHPK3PXP`
`bob`	developer	`test-password-123`	`JBSWY3DPEHPK3PXP`
`carol`	developer	`test-password-123`	`JBSWY3DPEHPK3PXP`

info

use any totp authenticator app with the secret JBSWY3DPEHPK3PXP to generate 2fa codes for login.

open two terminals:

# terminal 1: start the backend server on port 9000
pnpm dev
 
# terminal 2: start the web dev server on port 5173
pnpm dev:web

the vite dev server proxies /api/* and /ws/* requests to the backend server on port 9000.

open http://localhost:5173 in your browser and log in with any of the seed credentials.

script	description
`pnpm dev`	start the server
`pnpm dev:web`	vite dev server (port 5173)
`pnpm dev:seed`	seed test data
`pnpm build`	build all packages
`pnpm test`	run unit tests
`pnpm test:all`	run all tests including playwright e2e
`pnpm test:coverage`	run tests with v8 coverage reports
`pnpm lint`	type-check all packages
`pnpm publish:all`	publish all packages to npm

whenever you modify types in packages/protocol, rebuild:

pnpm --filter @overlordai/protocol build