Skip to content
toozejPublic

About

Tools and web-apps

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

tools

GitHub Actions CI Workflow Status GitHub Actions Release Workflow Status Docker Pulls GitHub Downloads (all assets, all releases)

Tools and web-apps

Usage

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.

Production Mode

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
  • 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

Fly.io

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=false

The 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.com

Follow the DNS target printed by fly certs add; do not allocate a dedicated IPv4 address, which is outside the legacy Hobby free allowance.

Development Usage

For development, docker-compose-dev.yml is used. This allows you to develop without affecting your production docker-compose.yml.

Start Development Services

  • 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

Stop Development Services

  • 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

Clean Rebuild in Development

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

Update Go versions and dependencies

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-converter

make 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.

manage

  • install uv
  • install pre-requisite packages
uv sync

"new" mode

  • 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

"copy" mode

  • 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" mode

  • Remove app
uv run manage remove old-app

# or skip confirmation with
uv run manage remove old-app --force

Supported Languages

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

Building and Deployment

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 (HTML, JS static)

Static apps are built once and served by nginx. Build output is stored in Docker volumes.

Server Apps (JS server, Go)

Server apps run as long-running containers proxied by nginx via the backend network.

Template Files

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

  • 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

About

Tools and web-apps

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages