slugkit

a federated website template and management toolkit.

This repository currently contains the Slugkit toolkit docs and an in-repo template website at template/site. The template site is used for CLI/API testing and is the source that future slug init work should copy into standalone site projects. Generated sites should not include or require editing the slug CLI source.

Prerequisites

• Node.js 24+
• npm, which is used by the current project scripts and workspaces
• Overmind for make dev
• Docker with Docker Compose for local Garage media storage

Installation

npm install

Environment

Copy the example environment file before starting local services:

cp .env.example .env

Current local variables:

• APP_HOST - local Hono template-site bind address. Defaults to 0.0.0.0, which makes the dev site reachable from another computer on the same LAN.
• APP_PORT - local Hono template-site port. Repository development defaults to 3013; generated sites retain their default 3000. APP_PORT is preferred for local development because Overmind reserves PORT internally.
• DATABASE_PATH - SQLite database path used by template-site migration commands.
• S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_FORCE_PATH_STYLE, S3_PUBLIC_URL - S3-compatible media storage settings. Local development uses Garage from make dev; production homelab deployments should override these with the k3s Garage endpoint and credentials.
• MEDIA_MAX_UPLOAD_BYTES - maximum accepted media upload size in bytes.
• MEDIA_ALLOWED_MIME_TYPES - comma-separated allowed media MIME types.

Local development uses Docker Compose to run Garage through Overmind. Run make garage-setup once to create the local Garage bucket/key and write media credentials before normal development.

To use another local port, change only APP_PORT in .env (for example, APP_PORT=3010) and restart with make dev. The listener, local site URL defaults, canonical links, and default ActivityPub identity then use http://localhost:3010. APP_PORT takes precedence over PORT; with neither set, the listener and template default use 3000. Outside production, local stored URLs are resolved to that port at runtime without changing the database. Public site URLs and production site identities are not rewritten.

Leave ACTIVITYPUB_PUBLIC_ORIGIN unset for local development so federation defaults follow the configured port. An explicit origin is authoritative, even if it names a different local port. If your .env came from an older example, remove its ACTIVITYPUB_PUBLIC_ORIGIN=http://localhost:3000 line to use the automatic local default. Production federation should keep its stable explicit HTTPS origin. See docs/dev-port-overrides.md for precedence and verification.

Repository Structure

cli/                `slug` CLI foundation
template/site/      In-repo Slugkit website template used by future slug init work
docs/               Architecture, API, CLI, and template specs
scripts/            Local automation scripts

The template site has its own README at template/site/README.md. Its Slugkit API surface is mounted under /api/v1, including /api/v1/health, /api/v1/meta, /api/v1/openapi.json, and /api/v1/docs. Copied sites should edit content and site identity in template/site/src/config/site.ts and public Tailwind styling in template/site/src/styles/tailwind.css or the utility classes in template/site/src/templates/public.tsx.

How to Work on This Project

Start the Dev Environment

make dev

This starts all services defined in Procfile.dev through Overmind and returns immediately. The current Procfile starts Docker Compose, including Garage for S3-compatible media storage, the Tailwind CSS watcher, and the Hono template-site app service. If Docker Compose is unavailable or Garage cannot start, the Docker process fails visibly instead of reporting a fake running service.

A clean local database follows the same first-run setup flow as a generated site. To explicitly seed the repository-only example actor and mark setup complete for fixture-dependent development, stop the environment and run SLUGKIT_DEVELOPMENT_FIXTURE=true make dev. Generated sites do not enable this flag.

Configure Local Garage

Run this once before normal development, and rerun it only after resetting local Garage data or changing local media settings:

make garage-setup

The setup command starts the local Garage container if needed, creates the slugkit-dev bucket and access key, grants bucket permissions, and writes S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY into .env and template/site/.env. Slugkit defaults Garage to ports 3930-3933 to avoid collisions with other local projects. After this one-time setup, make dev simply starts the configured services through Overmind.

View Logs

# Connect to the Overmind tmux session
make dev-logs

# Quick peek at recent logs
make dev-tail

Check Status

make dev-status

Stop the Dev Environment

make dev-stop

Run Build, Tests, and Linting

npm run build
make check

Slugkit development site

The toolkit development environment uses port 3013, leaving port 3000 available for Rott. Its API base address is http://localhost:3013/api/v1; that route serves the packaged slugkit-management-api contract 1.1.0. Start it with make dev, then verify the globally configured development entry with slug --site slugkit-dev doctor --json. Set only that entry's API address and use a credential issued by this local site; do not reuse a different site's key. make dev-config maintains the separate repository-local CLI config without replacing the global config.

The toolkit's Garage service uses ports 3930–3933. Existing local environments should update those settings and S3_ENDPOINT in .env and template/site/.env to avoid the other websites' Garage services. Generated sites retain their own defaults. Remove an obsolete loopback ACTIVITYPUB_PUBLIC_ORIGIN override to let the local origin follow APP_PORT; this preserves stored actor keys and identity records.

Run the CLI Locally

make slug builds and runs the CLI from the repository root, using the named dev site already stored in .slug/dev.yaml. Create or refresh that local config with make dev-config when needed. Relative file arguments resolve from the repository root; absolute paths work unchanged. Quote paths and values containing spaces inside ARGS, as shown below.

make slug ARGS="--help"
make slug ARGS="version --json"
make slug ARGS="doctor"
make slug ARGS="media upload template/site/src/assets/slugkit-logo.png --alt 'Slugkit logo'"
make slug ARGS="post import 'content/My first post.md'"

You can also run the built CLI directly from the repository root without npm workspace execution changing the working directory:

npm run build --workspace @evcraddock/slug-cli
node ./cli/dist/index.js --help
node ./cli/dist/index.js --config .slug/dev.yaml --site dev doctor

Run Template Database Migrations

npm run db:migrate --workspace @slugkit/template-site
npm run db:status --workspace @slugkit/template-site

Feature-specific tables are added by the future vertical feature slice that needs them.

Before Opening a PR

make pre-pr

Available Make Commands

make help

Manual Setup Notes

If make dev fails because overmind is missing, install Overmind and rerun make dev. The dev server listens on http://localhost:$APP_PORT, with APP_PORT=3013 from .env.example.

To open the dev site from another computer on the same network, start make dev, find this machine's LAN IP address, and open http://<lan-ip>:3013. The host firewall must allow inbound connections to that port.

License

MIT