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):

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

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.

Build the Binary

Build the complete Anubis binary:

npm run build

This runs npm run assets followed by:

go build -o ./var/anubis ./cmd/anubis

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

Run Locally

Run Anubis in development mode:

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:

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:

go generate ./...

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

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:

rm -rf web/static/*.js web/static/*.css
npm run assets

Build Fails

Ensure all prerequisites are installed:

go version  # Should be 1.24.2+
node --version
esbuild --version