Installation

Calendarpit is available through Docker, Homebrew, and standalone downloads. See GitHub Releases for the current version.

• Docker Compose: Use it for a container environment.
• Homebrew: Use it for a local CLI.

Both include the API, OAuth server, admin UI, and SQLite. Neither requires Bun, Node.js, Google credentials, or a separate database. Calendarpit is not distributed through npm.

DockerCopy Anchor Link

docker run --rm \
  -p 127.0.0.1:4173:4173 \
  -v calendarpit-data:/data \
  ghcr.io/iktakahiro/calendarpit:latest

The image:

• Targets Linux amd64 and arm64, including Docker on Apple Silicon.
• Runs as a non-root user.
• Persists SQLite in /data/calendarpit.sqlite.
• Is tagged latest and with each release version. Pin a version tag when CI needs a fixed version.

Keep the named volume to retain data across container recreation. For disposable tests, use -e CALENDARPIT_DATABASE=:memory:.

The host port is published only on loopback. Inside the container, Calendarpit explicitly binds 0.0.0.0.

Docker ComposeCopy Anchor Link

Add this service and volume to your compose.yaml:

services:
  calendarpit:
    image: ghcr.io/iktakahiro/calendarpit:latest
    ports:
      - '127.0.0.1:4173:4173'
    volumes:
      - calendarpit-data:/data

volumes:
  calendarpit-data:

docker compose up -d calendarpit
docker compose logs calendarpit
docker compose down

down preserves the volume. down -v deletes its saved data.

The image includes a health check. To wait for Calendarpit in another service, use depends_on: { calendarpit: { condition: service_healthy } }.

If you override the container port, set CALENDARPIT_PORT as well as the port mapping. The health check then uses the same port.

Addresses depend on who makes the requestCopy Anchor Link

• Keep the browser's OAuth authorization URL on the host-accessible address.
• A containerized backend uses the Compose address for token exchange and Calendar API requests.
• The OAuth redirect_uri must exactly match the fixture's registered URI. It must also be accessible to the browser.

Webhook receiversCopy Anchor Link

Webhook addresses are resolved by Calendarpit:

• Receiver service in Compose: For a service named app, allow CALENDARPIT_WATCH_HOSTS=app and register http://app:<port>/<path>.
• Process on the host: Docker Desktop provides host.docker.internal. On Linux Docker Engine, add extra_hosts: ["host.docker.internal:host-gateway"]. Allow that hostname with CALENDARPIT_WATCH_HOSTS.

The receiving process must listen on an address reachable from the container. See Watch notifications.

HomebrewCopy Anchor Link

brew install iktakahiro/tap/calendarpit
calendarpit serve

The tap installs a standalone executable for macOS or Linux. Bun and Node.js are not required.

Run it in your project's directory so the default SQLite path belongs to that project.

To update:

brew update
brew upgrade iktakahiro/tap/calendarpit

Standalone downloadCopy Anchor Link

From GitHub Releases, download the archive that matches your OS and CPU, together with SHA256SUMS. Verify the archive checksum before you extract it. For example, on Apple Silicon:

shasum -a 256 calendarpit-0.9.0-darwin-arm64.tar.gz
tar -xzf calendarpit-0.9.0-darwin-arm64.tar.gz
./bin/calendarpit serve

Compare the printed hash with the matching line in SHA256SUMS.

Windows archives contain bin/calendarpit.exe. No Bun, Node.js, or asset directory is required.

Updates and storageCopy Anchor Link

When you choose to upgrade:

• Docker: Update the exact image tag.
• Homebrew: Use brew upgrade.

Before upgrading, stop Calendarpit and back up its SQLite directory or Docker volume.

See Storage and restarts and Run and configure.