Installation Guide
Windows desktop, build from source, server/NAS deployment
System Requirements
| Operating System | Windows 10/11, macOS 12+, Linux |
| Processor | x64 / ARM64 |
| Memory | 4 GB+ |
| Disk Space | 100 MB+ |
Windows Install (Recommended)
Download the installer, double-click to run through the wizard. The installer writes to Program Files and optionally adds the app to PATH; admin consent is required once.
Download the Windows installer from the website (~30 MB)
Double-click to run the installer and follow the wizard (optional: add app directory to PATH, install local CA to system trust store)
Launch Ginkgo Backup and enter your activation code to complete first-launch activation
Build from Source
Requires Go 1.25+. Suitable for macOS/Linux users or custom builds.
Shell
git clone https://github.com/ginkgo-backup/ginkgo.git
cd ginkgo
go build -tags oss -o ginkgo-server ./cmd/ginkgo-server
go build -tags oss -o ginkgo-cli ./cmd/ginkgo-cliOpen-source builds use -tags oss to exclude enterprise features. For FUSE mount support on Linux/macOS, build with CGO_ENABLED=0.
Headless Mode (Server / NAS)
Run on a server or NAS without a GUI. Manage everything via HTTP API and CLI.
Shell
./ginkgo-server --tls-auto
# API: https://127.0.0.1:9275
# Token auto-generated on first run, saved to ~/.ginkgo-backup/config.json
# headless mode auto-enables TLSOn first start, the auto-generated Token is printed to stdout and saved to ~/.ginkgo-backup/config.json. When listening on 0.0.0.0, set a WebUI password with --set-password before exposing the API.
Command-Line Flags
The following flags can be passed when starting ginkgo-server:
| Flag | Default | Description |
|---|---|---|
--port | 9275 | API server port (env: GINKGO_API_PORT) |
--addr | 0.0.0.0 | API listen address (env: GINKGO_API_ADDR; defaults to all interfaces) |
--open | true | Open browser on launch |
--debug | false | Debug mode (single process, disables watchdog) |
--tls-cert | — | TLS certificate file path |
--tls-key | — | TLS private key file path |
--tls-auto | false | Auto-generate local CA and server certificate (auto-enabled in headless mode) |
--tls-trust | false | Install local CA to system trust store and exit (requires admin) |
--set-password | — | Set WebUI access password and exit (recommended when listening on 0.0.0.0) |
--no-watchdog | false | Disable watchdog auto-restart |
Environment Variables
Environment variables override the corresponding command-line flags:
| Variable | Description |
|---|---|
GINKGO_API_PORT | API server port (overrides --port) |
GINKGO_API_ADDR | API listen address (overrides --addr; defaults to 0.0.0.0) |
GINKGO_TOKEN | Auth token (overrides auto-generated) |
GINKGO_TLS | Set to 1 to enable TLS (CLI side; equivalent to --tls) |
GINKGO_NO_WATCHDOG | Set to 1 to disable watchdog auto-restart |
Verify Installation
After install, verify the server is running:
Shell
# Health check (no auth required)
curl http://127.0.0.1:9275/api/v1/health
# List backup sources (requires Token)
curl -H "Authorization: Bearer <TOKEN>" http://127.0.0.1:9275/api/v1/sourcesUpgrading
Stop the running service
Replace the old executable with the new version
Restart — database migrations run automatically