Installation

Download

There is nothing to compile and no runtime to install. Pick the build that matches your machine and pull it with curl.

amd64 covers most cloud VPS and desktops; arm64 covers modern ARM servers and the Raspberry Pi 4/5; armv7 covers 32-bit ARM boards.

Verify the download

Every release ships a checksums.txt with the SHA-256 of each binary. Pull it next to your download and check they match — the same SHA-256 check gtcnsl's own self-update runs before swapping the binary.

curl -fsSLO https://dl.gtcnsl.com/v1.3.0/checksums.txt
sha256sum --check --ignore-missing checksums.txt

Put it on PATH

The install snippet already writes to /usr/local/bin/gtcnsl and sets the executable bit. If you downloaded by hand, do it explicitly:

sudo install -m 0755 gtcnsl-v1.3.0-linux-amd64 /usr/local/bin/gtcnsl

Confirm it runs

gtcnsl version

You should see the version, build commit, and target arch. If the command is not found, your shell has not picked up /usr/local/bin yet — open a new session.

Supported platforms

gtcnsl is tested on the distributions and architectures below. Other modern systemd-based Linux distros are likely fine but unverified.

Serving profiles: HTTP, or HTTPS out of the box

By default gtcnsl gitea install serves plain HTTP on :3000 — the right choice behind a reverse proxy or on an internal network. If Gitea should terminate TLS itself, pick a profile at install time:

# Built-in Let's Encrypt on :443 (:80 answers the ACME challenge and redirects).
# --acme-tos is your explicit consent to the CA's Terms of Service — never implied.
gtcnsl gitea install --yes --serving https-acme \
    --domain git.example.com --acme-email you@example.com --acme-tos

# Your own certificate (corporate CA, wildcard) — port defaults to 443.
gtcnsl gitea install --yes --serving https-manual \
    --domain git.example.com \
    --cert-file /etc/gitea-tls/fullchain.pem --key-file /etc/gitea-tls/privkey.pem

Both HTTPS profiles run preflights before anything is downloaded: the target ports must be bindable, certificate files must exist and be readable by the git user, and for ACME the domain is checked (best effort) to resolve to this host. gtcnsl's systemd unit grants CAP_NET_BIND_SERVICE, so the non-root git user binds :443/:80 without tricks.

Already installed over HTTP? Switch a live instance without reinstalling:

gtcnsl gitea enable-https --yes --serving https-acme \
    --domain git.example.com --acme-email you@example.com --acme-tos

The switch rides the declarative config machinery — atomic write with a backup, restart, health check — and rolls back to the working HTTP config automatically if anything fails (certificate not issued, DNS not pointing here yet). On a hand-written unit that lacks the capability for ports below 1024, --grant-caps deploys a small gtcnsl-owned drop-in; your unit file itself is never edited. gtcnsl doctor gains a coherence probe that catches an https-on-:443 config whose unit can't actually bind it.

Already run Gitea? Adopt it

If this host already has a Gitea — set up by hand or by another tool — you don't reinstall. gtcnsl gitea install detects it and upgrades in place (see Upgrades), and gtcnsl gitea adopt brings it under management without moving any data:

gtcnsl gitea adopt                      # dry-run: prints the plan, changes nothing
gtcnsl gitea adopt --yes --emit-template app.ini.tmpl
gtcnsl gitea adopt --yes --unit         # optional: normalize a hand-written unit

Adopt extracts the secrets from app.ini into secrets.ini with the same values (no restart), tightens a world-readable app.ini, and emits a secrets-free template you commit to git — unlocking config apply and secrets rotate. --unit splits a hand-written service file into gtcnsl's managed base plus an operator-owned drop-in, with systemd itself proving the result behaves identically (automatic rollback otherwise).

Next steps

With the binary on PATH, you are three commands away from a running Gitea with CI.