Customizing your fork

After forking stanza-go/standalone, there are a few things to change before you start building. This page covers each one.

Change the Go module path

The standalone repo uses github.com/stanza-go/standalone as its module path. Update it to match your fork:

cd api

# Update go.mod
sed -i '' 's|github.com/stanza-go/standalone|github.com/your-org/your-app|g' go.mod

# Update all imports across the codebase
find . -name '*.go' -exec sed -i '' 's|github.com/stanza-go/standalone|github.com/your-org/your-app|g' {} +

After renaming, verify it compiles:

go vet ./...

Change the data directory

By default, all application state lives in ~/.stanza/. The data directory name is defined in api/datadir/datadir.go:

const defaultName = ".stanza"

Change it to match your project:

const defaultName = ".my-app"

In production, override with the DATA_DIR environment variable — point it to your persistent volume:

DATA_DIR=/data ./my-app

The directory structure is created automatically on first boot:

~/.my-app/
├── database.sqlite      ← all data
├── logs/                ← structured logs
├── uploads/             ← user uploads
├── backups/             ← automatic backups
└── config.yaml          ← runtime config overrides

Change the app name and metadata

Update the app name in api/main.go — look for the health check and version info:

// In provideServer or wherever the health response is built:
"app": "my-app",

Also update the Makefile and Dockerfile if you've renamed the binary.

Environment variables

These environment variables control runtime behavior. Set them in your shell, .env file, or container platform:

For local development, the minimum is:

export STANZA_AUTH_SECURE_COOKIES=false

For production, set at minimum DATA_DIR and STANZA_AUTH_SIGNING_KEY.

Pre-built API routes

The standalone app ships with 33 modules. Here are all the endpoints, grouped by area.

Admin authentication

User authentication

Password reset

Admin panel endpoints

All admin endpoints require an authenticated admin session.

User endpoints

All user endpoints (except auth) require an authenticated user session.

Local development with go.work

When you need to develop your app against a local copy of the framework (e.g., to add a framework feature or debug an issue), use a go.work file:

# From your project root (parent of api/)
cat > go.work << 'EOF'
go 1.26.1

use (
    ./api
    ../path/to/framework
)
EOF

With go.work in place, Go resolves github.com/stanza-go/framework from the local directory instead of the module cache. Changes to the framework are picked up immediately — no need to tag or publish.

When you're done and want to use the published framework version again, simply delete the go.work file.

What to change — checklist

1. Module path in api/go.mod + all import statements
2. Data directory name in api/datadir/datadir.go
3. App name in health check and metadata
4. Auth signing key — set STANZA_AUTH_SIGNING_KEY for persistent sessions
5. CORS origins — update when your frontend runs on a different domain
6. Email config — set Resend API key and from address when ready