> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emplio.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Build and run Emplio from source

> Clone the repo, build every image from your own code with ./setup.sh --build, run the dev servers with Bun 1.3, and run the type check and tests.

To run your own changes, build Emplio's images from the code instead of downloading them. You need [Bun](https://bun.sh) 1.3 and [Docker](https://docs.docker.com/get-docker/).

**1. Clone and install**

```bash theme={null}
git clone https://github.com/emplio-app/emplio && cd emplio
bun install
```

**2. Build and start**

```bash theme={null}
./setup.sh --build
```

The first time, it asks the same three questions as the installer and writes `.env`. A build takes about 8 minutes on a small server. Run it again after each change.

**3. Check the types**

```bash theme={null}
bun run typecheck
```

Run this before you push.

## Dev servers

```bash theme={null}
bun run dev
```

This runs the web app (`next dev`) and the API (`bun --watch`) together, reloading as you edit. The API needs Postgres, Gitea and the runner to reach. It reads the same settings the app container gets: `DATABASE_URL`, `GITEA_URL`, `GITEA_TOKEN`, `COMPUTER_RUNNER_URL`, `RUNNER_TOKEN`, `ENCRYPTION_KEY` and `OPENROUTER_API_KEY`. Run `bun run db:migrate` once against a fresh database.

The runner joins the `emplio-app` container to each person's network, so computers and browsers work end to end only with the app in Docker. Use `./setup.sh --build` to check those.

## Tests

| What | Command | Needs |
| - | - | - |
| Backend | `cd backend && bun run db:migrate && bun run test` | Postgres and Gitea |
| Runner | `bun test runner` | Nothing; Docker is faked |
| Whole install | `bash docker/smoke.sh` | Docker, and a clean copy with no `.env` |

[`.github/workflows/ci.yml`](https://github.com/emplio-app/emplio/blob/main/.github/workflows/ci.yml) shows exactly how CI starts Postgres and Gitea for the backend tests. CI runs all three on every pull request, so you can leave the tests to it.

> [!TIP]
>
> `docker/smoke.sh` builds everything, signs up, runs a real computer and browser, and removes all of it afterwards.

> [card] [Project map](https://docs.emplio.app/developers/project-map.md)
>
> What each folder holds.

> [card] [Contributing](https://docs.emplio.app/contribute/contributing.md)
>
> Open a pull request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.