Install for development
Facet runs from source on Linux and macOS. If you only want to try the product, run the Docker Compose stack instead — see Deploy to production.
Prerequisites
Section titled “Prerequisites”Install these tools first. The table lists what each one serves:
| Tool | Notes |
|---|---|
| Crystal 1.21 | The toolchain in use. The agent-cr shard needs Crystal 1.19 or newer. |
| PostgreSQL 14 or newer | One instance for the app. The ulid() function needs PostgreSQL 14. |
| Redis | Required. The event bus, sessions, OAuth codes, and rate limits use it. |
| Node.js 20+ and pnpm | Frontend, CLI package, E2E runner. pnpm only — the lockfiles are pnpm-lock.yaml. |
| Caddy | The dev proxy. scripts/dev expects it on PATH. |
| Lua 5.4 or 5.5 headers | The lua shard links the system library (liblua5.4-dev on Debian/Ubuntu). |
Get the code
Section titled “Get the code”Clone the repository:
git clone https://github.com/wearefacet/facet.gitcd facetConfigure
Section titled “Configure”Configuration lives in two files:
config.dev.yml— backend configuration (database, Redis, mail, artifacts).- the root
.env— shared addresses, notablyBACKEND_URL.
Bootstrap
Section titled “Bootstrap”Run the three scripts in order:
scripts/init # create the database, migrate, seed core doctypes + a dev adminscripts/import-fixtures # optional: load the sample CRM / HR / production domains./scripts/dev # Caddy + backend + frontend at https://facet.localhost:3443scripts/init runs facet db_reset seed:dev: it drops and re-creates the
database, applies all migrations, and seeds the core schema with a dev
administrator.
Open https://facet.localhost:3443 and sign in with the seeded dev
administrator: admin@example.tld / admin. This credential is for throwaway
dev data only — the platform refuses it in production.
What runs
Section titled “What runs”Three processes serve the stack:
./scripts/dev starts all processes in one terminal. Use
./scripts/dev --no-caddy for raw two-port mode (backend :3000, frontend
:5173).
Daily commands
Section titled “Daily commands”Backend (repository root):
| Command | Purpose |
|---|---|
make check |
Compile gate, no binary. Fastest signal on type errors. |
make build / make build_release |
Server binary into build/. |
make run |
Backend only. |
make test |
Full spec suite. Starts a throwaway PostgreSQL on port 5433 first. |
bin/ameba |
Crystal linter. |
Frontend (in frontend/):
| Command | Purpose |
|---|---|
pnpm check |
svelte-check — types, Svelte syntax, accessibility. |
pnpm lint |
Prettier + ESLint. |
pnpm test |
Vitest: pure logic + Storybook story play functions. |
pnpm storybook |
Component workbench. |
Next steps
Section titled “Next steps”- Read Domains, drafts and domain editors to learn how Facet organizes data.
- Read Deploy to production when you are ready to ship.