Tools and web-apps
This repository leverages Make targets to simplify common operations. For those who prefer direct Docker Compose commands, alternatives are provided.
- Ensure you have Docker Compose installed.
Runs the full tools stack using pre-built images from GitHub Container Registry (ghcr.io/toozej/tools).
- Copy and adjust the production compose file:
cp docker-compose-prod.yml docker-compose.yml
- Adjust as needed (ports, reverse proxy, env files, etc.)
- Start the full tools stack:
- Using
make:
make up
- Alternatively, using Docker Compose directly:
docker compose -f docker-compose.yml --profile build --profile runtime up -d
- Using
- Browse the apps at http://localhost:8080/
- Stop the full tools stack:
- Using
make:
make down
- Alternatively, using Docker Compose directly:
docker compose -f docker-compose.yml --profile build --profile runtime down --remove-orphans
- Using
fly.toml deploys the isolated docker-compose-fly.yml with Fly's native
multi-container Machine support. The self-hosted docker-compose-prod.yml and
nginx/conf.d/default.conf remain unchanged. All static app outputs are baked
into the one buildable nginx service; only tfgr runs as a prebuilt runtime
sidecar on a unique loopback port. No persistent volume is required.
The checked-in homepage colophon always contains the full app catalog. During
the Fly nginx image build, nginx/filter-fly-colophon.py removes the runtime
apps listed in nginx/fly-colophon-exclude.txt from a temporary copy before
building the homepage, so Fly only advertises apps that are actually present.
The configuration deliberately uses one shared-cpu-1x Machine with 256 MB
RAM, automatic stop/start, and no minimum running Machine count. A swap file
absorbs infrequent memory spikes without increasing the billable VM size. Keep
the first deploy at one Machine so it stays inside the legacy Hobby allowance:
flyctl deploy --ha=falseThe deploy-fly GitHub Actions workflow deploys the Fly configuration after
the release workflow's build-and-push job succeeds; it can also be started
manually from the Actions tab. Add a Fly deployment token as the
FLY_API_TOKEN repository secret before enabling automatic deployments.
Attach and verify the production hostname after deployment:
flyctl certs add tools.toozej.com
flyctl certs check tools.toozej.comFollow the DNS target printed by fly certs add; do not allocate a dedicated
IPv4 address, which is outside the legacy Hobby free allowance.
For development, docker-compose-dev.yml is used. This allows you to develop without affecting your production docker-compose.yml.
- To start the development environment (builds images if needed):
- Using
make:
make dev
- Alternatively, using Docker Compose directly:
docker compose -f docker-compose-dev.yml --profile build --profile runtime up --build -d
- Browse the apps at http://localhost:8080/
- Using
- To stop the development environment:
- Using
make:
make dev-down
- Alternatively, using Docker Compose directly:
docker compose -f docker-compose-dev.yml --profile build --profile runtime down --remove-orphans
- Using
To perform a clean rebuild (without cache) in development:
- Using
make:make dev-nc
- Alternatively, using Docker Compose directly:
docker compose -f docker-compose-dev.yml --profile build --profile runtime down --remove-orphans docker compose -f docker-compose-dev.yml --profile build --profile runtime build --no-cache --pull docker compose -f docker-compose-dev.yml --profile build --profile runtime up -d
The app modules, Makefile, CI jobs, and Go app Docker images use Go 1.27.4. Keep the CI and Docker versions at least as new as the app module requirements.
Run make update-go-version to set the latest stable Go version in each
apps/*/go.mod file and its Go Docker image. The target also updates the shared
Makefile and CI toolchains. This target requires Go, curl, jq, sed, and network access.
Use APP to update one app and the shared toolchains:
make update-go-version
make update-go-version APP=md-convertermake up runs this target before it starts Docker Compose. make update and
make update-validate run this target before they update app dependencies and
validate the apps. These targets also support APP. The Go commands can select
a newer toolchain when an app requires it. Go downloads that toolchain if needed.
An error during the Go version update stops the calling target.
Run python3 -m unittest discover -s tests -v to test Go version updates without network access.
CI runs these tests and builds each Go Docker image to check its toolchain.
CI blocks high and critical image findings when fixes are available.
The Go images install Debian security updates for Expat, kernel headers, and zlib where those packages are present.
- install uv
- install pre-requisite packages
uv sync- Create new Go app
uv run manage new my-service go- Create new JavaScript/NextJS app (static by default)
uv run manage new my-dashboard js- Create new JavaScript/NextJS app with server support (API routes, OAuth)
uv run manage new my-api js --server- Create new HTML/static site
uv run manage new my-site html- Standard git URL
uv run manage copy my-app https://github.com/user/repo.git- Kilocode app builder (paste the entire clone command)
uv run manage copy my-app "git clone https://x-access-token:eyJhbGc...@builder.kiloapps.io/apps/31df803a-a14a-4c33-82e9-d4b93a146db7.git"
- With path in repo
uv run manage copy my-app https://github.com/user/repo.git --path src/frontend- Remove app
uv run manage remove old-app
# or skip confirmation with
uv run manage remove old-app --force| Language | Command | Description |
|---|---|---|
go |
uv run manage new my-app go |
Go applications |
js |
uv run manage new my-app js |
NextJS/Bun apps (static export) |
js --server |
uv run manage new my-app js --server |
NextJS/Bun apps with API routes |
html |
uv run manage new my-app html |
Pure HTML/CSS/vanilla JS sites |
The tools repository supports two deployment patterns:
The existing Next.js app Dockerfiles use Node.js 26 Alpine for builds. Server app images also use Node.js 26 Alpine at runtime.
Static apps are built once and served by nginx. Build output is stored in Docker volumes.
Server apps run as long-running containers proxied by nginx via the backend network.
Templates are located in the templates/ directory:
| File | Purpose |
|---|---|
Dockerfile.go.template |
Go application Dockerfile |
Dockerfile.js.static.template |
NextJS static export Dockerfile |
Dockerfile.js.server.template |
NextJS server Dockerfile |
Dockerfile.html.template |
Pure HTML/CSS/JS Dockerfile |
.dockerignore.go |
Go .dockerignore template |
.dockerignore.js |
JavaScript .dockerignore template |
.dockerignore.html |
HTML .dockerignore template |
See templates/README.md for detailed template documentation.
- Generate colophon.json in repo root
uv run generate-colophon- Specify output location (e.g., for use by the homepage app)
uv run generate-colophon --output ./apps/homepage/src/data/colophon.json- Specify different repo location
uv run generate-colophon --repo /path/to/tools- Verbose mode for debugging
uv run generate-colophon -v