> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/TecharoHq/Anubis/llms.txt
> Use this file to discover all available pages before exploring further.

# Building Anubis

> Build Anubis from source and understand the build process

This guide explains how to build Anubis and its dependencies.

## Understanding the Build Process

Anubis embeds JavaScript and CSS assets directly into the Go binary. This means you **must build assets before any Go build or test operation**.

### Build Order

1. **Generate code** from templ templates and other generators
2. **Build frontend assets** (JavaScript and CSS)
3. **Compress assets** (gzip, zstd, brotli variants)
4. **Build Go binary** with embedded assets

## Build Assets

Build all frontend assets (required before any Go build):

```bash theme={null}
npm run assets
```

This script runs:

* `go generate ./...` - Generates Go code from `.templ` files
* `./web/build.sh` - Builds and bundles JavaScript from `web/js/`
* `./xess/build.sh` - Builds CSS from the xess framework
* Creates compressed variants (`.gz`, `.zst`, `.br`) for all static assets

<Warning>
  **CRITICAL**: Always run `npm run assets` before `go build` or `go test`. The Go binary embeds these assets. If you skip this step, your build will use stale or missing assets.
</Warning>

## Build the Binary

Build the complete Anubis binary:

```bash theme={null}
npm run build
```

This runs `npm run assets` followed by:

```bash theme={null}
go build -o ./var/anubis ./cmd/anubis
```

The compiled binary is written to `./var/anubis`.

## Run Locally

Run Anubis in development mode:

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

This builds assets and runs Anubis with:

* `--use-remote-address` flag (uses the client's real IP)
* `--target http://localhost:3000` (proxies to local dev server)

Equivalent to:

```bash theme={null}
npm run assets && go run ./cmd/anubis --use-remote-address --target http://localhost:3000
```

## Available Build Scripts

From `package.json`:

| Script              | Command                                                                                     | Description               |
| ------------------- | ------------------------------------------------------------------------------------------- | ------------------------- |
| `npm run assets`    | `go generate ./... && ./web/build.sh && ./xess/build.sh`                                    | Build all frontend assets |
| `npm run build`     | `npm run assets && go build -o ./var/anubis ./cmd/anubis`                                   | Full production build     |
| `npm run dev`       | `npm run assets && go run ./cmd/anubis --use-remote-address --target http://localhost:3000` | Run in dev mode           |
| `npm run container` | `npm run assets && go run ./cmd/containerbuild`                                             | Build container image     |
| `npm run format`    | `prettier -w . && go run goimports -w .`                                                    | Format all code           |

## Build Artifacts

After building, you'll find:

* `./var/anubis` - Main binary
* `web/static/` - Bundled JavaScript and CSS with compressed variants
* Generated Go files from `.templ` templates

## Code Generation

Anubis uses `go generate` for:

* **Templ templates**: `web/*.templ` files generate Go code
* **Stringer**: Enum types generate String() methods

Manually run code generation:

```bash theme={null}
go generate ./...
```

<Note>
  Generated files are committed to the repository, so you typically only need to regenerate after modifying `.templ` files or enum definitions.
</Note>

## Troubleshooting

### Assets Not Found at Runtime

If you see errors about missing assets:

1. Ensure you ran `npm run assets` before building
2. Check that `web/static/` contains `.js` and `.css` files
3. Rebuild completely: `npm run build`

### Stale Assets

If your changes aren't appearing:

```bash theme={null}
rm -rf web/static/*.js web/static/*.css
npm run assets
```

### Build Fails

Ensure all prerequisites are installed:

```bash theme={null}
go version  # Should be 1.24.2+
node --version
esbuild --version
```