Split the packages, publish releases from Gitea Actions, release 0.1.0
release / release (push) Successful in 7m7s
release / release (push) Successful in 7m7s
make deb now builds two packages: jarl-cli (the CLI, its completion and the ACME hooks, no scripts) and jarl (the server), which depends on jarl-cli of the same version. Pushing a v* tag runs .gitea/workflows/release.yml: it tests, builds the tarballs, the CLI for Linux, macOS and Windows (make cli-dist) and the .debs for amd64 and arm64, then scripts/gitea-release.sh creates the Gitea release and uploads the .debs to the Debian package registry, so servers install and upgrade with apt. The stats package's inode lookup is split by OS so the CLI builds for Windows. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
abrown38andClaude Opus 5.5 committed
1 parent
293e6ddd33
commit
4d00be53c3
16 files changed
+450
-84
No files matched your search
+2
-2
@@ -68,7 +68,7 @@ configuration, so `certbot renew` works unattended.
|
||||
Install the DNS API hook that comes with Jarl:
|
||||
|
||||
```sh
|
||||
cp contrib/acme.sh/dns_jarl.sh ~/.acme.sh/dnsapi/ # or from /usr/local/share/doc/jarl/contrib/
|
||||
cp contrib/acme.sh/dns_jarl.sh ~/.acme.sh/dnsapi/ # or from /usr/share/doc/jarl-cli/contrib/ (jarl-cli package)
|
||||
export JARL_SERVER=https://ns1.adbraun.lol:8053
|
||||
export JARL_TOKEN=$(cat /etc/jarl/certbot.token)
|
||||
acme.sh --issue --dns dns_jarl -d adbraun.lol -d '*.adbraun.lol'
|
||||
@@ -86,7 +86,7 @@ Jarl ships one, `contrib/lego/jarl-lego.sh`, which calls the `jarl` CLI
|
||||
(so jarl must be installed on the same host):
|
||||
|
||||
```sh
|
||||
sudo install -m 0755 contrib/lego/jarl-lego.sh /usr/local/bin/jarl-lego # or from /usr/local/share/doc/jarl/contrib/
|
||||
sudo install -m 0755 contrib/lego/jarl-lego.sh /usr/local/bin/jarl-lego # or from /usr/share/doc/jarl-cli/contrib/ (jarl-cli package)
|
||||
export EXEC_PATH=/usr/local/bin/jarl-lego
|
||||
export JARL_SERVER=https://ns1.adbraun.lol:8053
|
||||
export JARL_TOKEN=@/etc/jarl/certbot.token
|
||||
|
||||
@@ -25,6 +25,10 @@ Besides commands and flags, Tab completes:
|
||||
|
||||
## Setup
|
||||
|
||||
On the DNS server the CLI comes with Jarl. To use it from another machine,
|
||||
install just the `jarl-cli` package there, or copy the static `jarl` binary
|
||||
([install.md](install.md#just-the-cli-on-another-machine)).
|
||||
|
||||
```sh
|
||||
jarl config set server https://ns1.adbraun.lol:8053
|
||||
jarl config set token # paste the token at the prompt
|
||||
|
||||
+38
-5
@@ -49,7 +49,7 @@ make # bin/jarld, bin/jarl (CGO_ENABLED=0, version from ./VERSION),
|
||||
# and bin/completion/{jarl,jarld} (bash completion)
|
||||
make test # go vet, gofmt check, go test ./...
|
||||
make e2e # scripts/e2e.sh
|
||||
make deb # dist/jarl_<version>_<arch>.deb (DEB_ARCH=arm64 etc. cross-builds)
|
||||
make deb # dist/jarl_<version>_<arch>.deb (server) and jarl-cli_<version>_<arch>.deb (DEB_ARCH=arm64 etc. cross-builds)
|
||||
```
|
||||
|
||||
### The Debian package
|
||||
@@ -70,7 +70,7 @@ To try the package without installing it on your machine:
|
||||
|
||||
```sh
|
||||
docker run --rm -it -v "$PWD/dist:/pkg:ro" debian:trixie \
|
||||
sh -c 'apt-get update && apt-get install -y /pkg/jarl_*_amd64.deb && bash'
|
||||
sh -c 'apt-get update && apt-get install -y /pkg/jarl_*_amd64.deb /pkg/jarl-cli_*_amd64.deb && bash'
|
||||
```
|
||||
|
||||
### Shell completion
|
||||
@@ -154,7 +154,40 @@ files are embedded at build time, so rebuild jarld after changes.
|
||||
|
||||
## Releasing
|
||||
|
||||
1. Move the "Unreleased" section of `CHANGELOG.md` under the new version
|
||||
and date.
|
||||
1. Move the "Unreleased" section of `CHANGELOG.md` under
|
||||
`## [<version>] - <date>`.
|
||||
2. Put the version in `VERSION`.
|
||||
3. `make test && JARL_BIND_ROOT=... make e2e && make dist`.
|
||||
3. `make test && JARL_BIND_ROOT=... make e2e` (CI runs only `make test`;
|
||||
it has no BIND).
|
||||
4. Commit, tag and push: `git tag v<version> && git push origin main v<version>`.
|
||||
|
||||
The tag starts `.gitea/workflows/release.yml`, which checks that the tag
|
||||
matches `VERSION` and that `CHANGELOG.md` has the section, runs `make
|
||||
test`, builds everything (`make dist`, `make cli-dist`, `make deb` for
|
||||
amd64 and arm64) and runs `scripts/gitea-release.sh`. That creates the
|
||||
Gitea release (the CHANGELOG section as notes; the tarballs, the CLI for
|
||||
Linux, macOS and Windows, the `.deb`s and `SHA256SUMS` attached) and
|
||||
uploads the `.deb`s to the owner's Debian registry, distribution `stable`,
|
||||
component `main` ([install.md](install.md#from-the-package-registry)). A
|
||||
version with a hyphen (`1.0.0-rc.1`) becomes a pre-release; its packages
|
||||
get version `1.0.0~rc.1`, which apt sorts before `1.0.0`.
|
||||
|
||||
Pushing the same tag again (`git tag -f`, `git push -f`) re-runs it, and
|
||||
the script replaces the attachments and packages, so a failed release can
|
||||
simply be retried.
|
||||
|
||||
Once, on Gitea:
|
||||
|
||||
* Actions on for the repository (Settings → Repository → Actions), and a
|
||||
runner with the `ubuntu-latest` label: act_runner's default, which runs
|
||||
jobs in `docker.gitea.com/runner-images:ubuntu-latest`. The job
|
||||
downloads Go itself (`actions/setup-go`, from `go.mod`), so the runner
|
||||
needs internet access, or a mirror of the actions and Go.
|
||||
* A repository secret `RELEASE_TOKEN` (Settings → Actions → Secrets): an
|
||||
access token (User settings → Applications) with the `write:repository`
|
||||
and `write:package` scopes, from a user who can write to the repository.
|
||||
The job's automatic token can't be relied on to publish packages.
|
||||
|
||||
`scripts/gitea-release.sh` also runs by hand after the same builds, with
|
||||
`GITEA_URL`, `GITEA_REPO` (`owner/name`) and `GITEA_TOKEN` set; it needs
|
||||
`curl`, `jq` and `dpkg-deb`.
|
||||
+84
-12
@@ -12,6 +12,12 @@ to load Jarl's configuration the old one is put back automatically.
|
||||
|
||||
## 1. Build
|
||||
|
||||
Each release is already built: the Debian packages are in the Gitea
|
||||
package registry ([below](#from-the-package-registry)), and the release
|
||||
page (https://gitea.adbraun.lol/adam/jarl/releases) has the packages, the
|
||||
linux tarballs, and the CLI for Linux, macOS and Windows. Build it yourself
|
||||
for an unreleased version.
|
||||
|
||||
Jarl is two static binaries with no runtime dependencies (SQLite is
|
||||
compiled in). Building needs Go 1.27 or newer, on any machine:
|
||||
|
||||
@@ -30,23 +36,62 @@ package (below) and copy that.
|
||||
There are two ways: a Debian package, which is easiest to upgrade and
|
||||
remove, or `make install`.
|
||||
|
||||
### With the Debian package
|
||||
### With the Debian packages
|
||||
|
||||
There are two packages:
|
||||
|
||||
| Package | Holds | Install it |
|
||||
|---------|-------|-----------|
|
||||
| `jarl` | the server: `jarld`, its systemd units, the docs | on the DNS server |
|
||||
| `jarl-cli` | the `jarl` CLI, its bash completion, the ACME hooks | wherever you manage Jarl from; `jarl` depends on it |
|
||||
|
||||
#### From the package registry
|
||||
|
||||
Every release is published to Gitea's Debian registry (amd64 and arm64).
|
||||
Add it to apt once, and apt then finds `jarl-cli` by itself and
|
||||
`apt upgrade` brings new releases:
|
||||
|
||||
```sh
|
||||
make deb # dist/jarl_0.1.0_amd64.deb
|
||||
make deb DEB_ARCH=arm64 # for another architecture (also armhf, i386, ...)
|
||||
sudo apt install ./dist/jarl_0.1.0_amd64.deb
|
||||
sudo install -d /etc/apt/keyrings
|
||||
sudo curl -fsSL https://gitea.adbraun.lol/api/packages/adam/debian/repository.key -o /etc/apt/keyrings/jarl.asc
|
||||
echo "deb [signed-by=/etc/apt/keyrings/jarl.asc] https://gitea.adbraun.lol/api/packages/adam/debian stable main" \
|
||||
| sudo tee /etc/apt/sources.list.d/jarl.list
|
||||
sudo apt update
|
||||
sudo apt install jarl
|
||||
```
|
||||
|
||||
The packages are as visible as the Gitea account that owns them, not the
|
||||
repository: with a public account, apt needs no login even if the
|
||||
repository is private. For a private or limited account, give apt a token
|
||||
with the `read:package` scope in `/etc/apt/auth.conf.d/jarl.conf` (mode
|
||||
0600):
|
||||
|
||||
```
|
||||
machine gitea.adbraun.lol/api/packages/adam/debian
|
||||
login adam
|
||||
password <token>
|
||||
```
|
||||
|
||||
#### From files
|
||||
|
||||
Download the two `.deb` files from the release page, or build them:
|
||||
|
||||
```sh
|
||||
make deb # dist/jarl_0.1.0_amd64.deb and dist/jarl-cli_0.1.0_amd64.deb
|
||||
make deb DEB_ARCH=arm64 # for another architecture (also armhf, i386, ...)
|
||||
sudo apt install ./dist/jarl_0.1.0_amd64.deb ./dist/jarl-cli_0.1.0_amd64.deb
|
||||
```
|
||||
|
||||
Give apt both files: `jarl` needs `jarl-cli` of the same version.
|
||||
`make deb` needs only `dpkg-deb` (no root, no debhelper) and cross-builds
|
||||
for any architecture Go supports. apt also installs `bind9` (recommended)
|
||||
if it's missing. Installing the package:
|
||||
if it's missing. Installing the server package:
|
||||
|
||||
* puts the binaries in `/usr/bin`, bash completion in
|
||||
* puts `jarld` in `/usr/bin`, its bash completion in
|
||||
`/usr/share/bash-completion/completions`, the systemd units in
|
||||
`/usr/lib/systemd/system` (`jarl.service`, and `jarl-backup.service`
|
||||
with its daily `jarl-backup.timer`), the sysusers and tmpfiles files
|
||||
in `/usr/lib`, and the docs and contrib files in `/usr/share/doc/jarl`;
|
||||
in `/usr/lib`, and the docs in `/usr/share/doc/jarl`;
|
||||
* creates the `jarl` user (in group `bind`) and Jarl's directories, and
|
||||
writes `/etc/jarl/jarl.yaml` from the example on the first install. No
|
||||
file in `/etc` belongs to the package, so your configuration is never
|
||||
@@ -58,17 +103,44 @@ if it's missing. Installing the package:
|
||||
* doesn't start jarld: continue with [3. Configure](#3-configure), then
|
||||
`systemctl enable --now jarl` in step 8.
|
||||
|
||||
**Upgrading**: build and install the newer package the same way. A running
|
||||
jarld is restarted, and upgrades its database as it starts.
|
||||
`jarl-cli` installs `/usr/bin/jarl`, its completion, and
|
||||
`/usr/share/doc/jarl-cli` (the CLI, ACME and permissions docs, and the
|
||||
acme.sh and lego hooks in `contrib/`).
|
||||
|
||||
**Upgrading**: `sudo apt update && sudo apt upgrade` with the registry, or
|
||||
install the newer files the same way. A running
|
||||
jarld is restarted, and upgrades its database as it starts. Up to 0.1.0
|
||||
everything was one `jarl` package; installing the two new ones over it
|
||||
moves `/usr/bin/jarl` to `jarl-cli` by itself.
|
||||
|
||||
**Removing** (`sudo apt remove jarl`) stops jarld and the backup timer and
|
||||
removes the program, but named keeps running with the configuration Jarl
|
||||
removes the server (the CLI stays until you remove `jarl-cli` too), but named keeps running with the configuration Jarl
|
||||
last wrote. Even `apt purge jarl` keeps `/etc/jarl`, `/var/lib/jarl` (the
|
||||
database), `/var/backups/jarl` and the
|
||||
files in `/etc/bind/jarl`, `/var/lib/bind/jarl` and `/var/cache/bind/jarl`,
|
||||
since named.conf may still include them. Remove them by hand once named no
|
||||
longer uses them.
|
||||
|
||||
### Just the CLI, on another machine
|
||||
|
||||
To manage Jarl servers from your laptop or another server, install only
|
||||
`jarl-cli`. It needs nothing else and changes nothing on the machine (no
|
||||
users, services or directories):
|
||||
|
||||
```sh
|
||||
sudo apt install jarl-cli # with the registry above; or: sudo apt install ./jarl-cli_0.1.0_amd64.deb
|
||||
jarl config set server https://ns1.adbraun.lol:8053
|
||||
jarl config set token
|
||||
```
|
||||
|
||||
Elsewhere, download the CLI from the release page:
|
||||
`jarl-cli-<version>-<os>-<arch>` for Linux, macOS (`darwin`) and Windows
|
||||
(`.exe`), with their checksums in `SHA256SUMS`. It is one static file; put
|
||||
it in your PATH as `jarl` (on macOS, `xattr -d com.apple.quarantine jarl`
|
||||
lets an unsigned download run). `make cli-dist` builds the same files, and
|
||||
`make` builds it for this machine in `bin/`. [cli.md](cli.md)
|
||||
explains the setup, and several servers in one configuration.
|
||||
|
||||
### With make install
|
||||
|
||||
On the DNS server, as root:
|
||||
@@ -297,8 +369,8 @@ without dropping connections. More in [acme.md](acme.md).
|
||||
## Upgrading
|
||||
|
||||
```sh
|
||||
make && sudo make install
|
||||
sudo systemctl restart jarl
|
||||
sudo apt update && sudo apt upgrade # Debian packages from the registry
|
||||
make && sudo make install && sudo systemctl restart jarl # make install
|
||||
```
|
||||
|
||||
Database migrations run automatically at startup. Before an upgrade, take
|
||||
|
||||
+1
-1
@@ -14,7 +14,7 @@
|
||||
| Restart / reload TLS | `systemctl restart jarl` / `systemctl reload jarl` |
|
||||
| Work on the server itself | `sudo jarl ...`: root uses jarld's local socket and needs no token ([cli.md](cli.md#on-the-server-itself)) |
|
||||
| Renew or replace a token | `jarl token rotate NAME --grace 1h` (same grants, new secret; [permissions.md](permissions.md#rotating-a-token)). `jarl token list --all --expiring` shows those that expire within 14 days |
|
||||
| Upgrade Jarl | Debian package: build the new one and `sudo apt install ./dist/jarl_*.deb`; otherwise `make && sudo make install && sudo systemctl restart jarl`. jarld upgrades its database when it starts |
|
||||
| Upgrade Jarl | Debian packages: build the new ones and `sudo apt install ./dist/jarl*_amd64.deb` (server and CLI); otherwise `make && sudo make install && sudo systemctl restart jarl`. jarld upgrades its database when it starts |
|
||||
|
||||
Restarting jarld doesn't affect DNS: named keeps serving the files it
|
||||
loaded. jarld is only needed to make changes.
|
||||
|
||||
Reference in new issue
Block a user