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. Defaults to 3000 when unset. 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.

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.

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 3910-3913 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

Run the CLI Locally

make slug uses the API base URL already stored in .slug/dev.yaml. Create or refresh that local config with make dev-config when needed.

make slug ARGS="--help"
make slug ARGS="version --json"

You can also run the workspace CLI directly:

npm exec --workspace @evcraddock/slug-cli -- slug --help

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=3000 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>:3000. The host firewall must allow inbound connections to that port.

License

MIT