docs: add section on adding the Gitea repo to a Debian machine
Expands the brief client-side steps into a standalone section covering prerequisites, fetching the repository key, the one-line and deb822 source forms, auth for a private owner, install and verification, troubleshooting, and removing the repo. Step 4 of the publishing flow now points at it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
root
parent
d8e5f2796e
commit
54d8e54205
@ -60,27 +60,8 @@ To check the upload, look at the owner's **Packages** tab in Gitea, or run
|
||||
|
||||
### 4. Install on each machine
|
||||
|
||||
```bash
|
||||
sudo curl -fsSL https://git.dasfad.com/api/packages/mmainguy/debian/repository.key \
|
||||
-o /etc/apt/keyrings/gitea-mmainguy.asc
|
||||
echo 'deb [signed-by=/etc/apt/keyrings/gitea-mmainguy.asc] https://git.dasfad.com/api/packages/mmainguy/debian bookworm main' \
|
||||
| sudo tee /etc/apt/sources.list.d/gitea-mmainguy.list
|
||||
sudo apt update && sudo apt install cloudflared-tunnel
|
||||
|
||||
sudo cloudflared-tunnel-setup --hostname app.example.com --port 3000
|
||||
# or: --token <TUNNEL_TOKEN> or: --quick
|
||||
```
|
||||
|
||||
Installing the package doesn't start a tunnel. `cloudflared-tunnel-setup` does
|
||||
that, and it's safe to re-run to change the mode or port.
|
||||
|
||||
If the Gitea owner is private, apt needs credentials. Keep them out of the
|
||||
world-readable sources file:
|
||||
|
||||
```bash
|
||||
printf 'machine git.dasfad.com\nlogin mmainguy\npassword <read-only token>\n' \
|
||||
| sudo install -m 0600 /dev/stdin /etc/apt/auth.conf.d/gitea.conf
|
||||
```
|
||||
See [Adding the Gitea repo to a Debian machine](#adding-the-gitea-repo-to-a-debian-machine)
|
||||
below for the client side.
|
||||
|
||||
### 5. Release an update
|
||||
|
||||
@ -92,6 +73,112 @@ echo 1.0.1 > VERSION # must change every release; Gitea won't overwrite a ver
|
||||
Machines pick it up with `apt upgrade`. If the tunnel is running, the upgrade
|
||||
restarts it.
|
||||
|
||||
## Adding the Gitea repo to a Debian machine
|
||||
|
||||
Do this once per machine that should install `cloudflared-tunnel` from Gitea.
|
||||
It works on Debian 11/12/13 and on Ubuntu. Substitute your own URL, owner and
|
||||
distribution wherever the examples say `git.dasfad.com`, `mmainguy` and
|
||||
`bookworm` — they must match `GITEA_URL`, `GITEA_OWNER` and `DIST` from
|
||||
`publish.env`.
|
||||
|
||||
### 1. Prerequisites
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y curl ca-certificates
|
||||
sudo install -d -m 0755 /etc/apt/keyrings
|
||||
```
|
||||
|
||||
`/etc/apt/keyrings` already exists on Debian 12 and newer; creating it is
|
||||
harmless and keeps the steps the same on older releases.
|
||||
|
||||
### 2. Fetch the repository signing key
|
||||
|
||||
Gitea serves it from the registry itself:
|
||||
|
||||
```bash
|
||||
sudo curl -fsSL https://git.dasfad.com/api/packages/mmainguy/debian/repository.key \
|
||||
-o /etc/apt/keyrings/gitea-mmainguy.asc
|
||||
sudo chmod 0644 /etc/apt/keyrings/gitea-mmainguy.asc
|
||||
```
|
||||
|
||||
Confirm you got a key and not an HTML error page:
|
||||
|
||||
```bash
|
||||
head -1 /etc/apt/keyrings/gitea-mmainguy.asc # -----BEGIN PGP PUBLIC KEY BLOCK-----
|
||||
```
|
||||
|
||||
### 3. Add the apt source
|
||||
|
||||
```bash
|
||||
echo 'deb [signed-by=/etc/apt/keyrings/gitea-mmainguy.asc] https://git.dasfad.com/api/packages/mmainguy/debian bookworm main' \
|
||||
| sudo tee /etc/apt/sources.list.d/gitea-mmainguy.list
|
||||
```
|
||||
|
||||
Or, if you prefer the deb822 format, write
|
||||
`/etc/apt/sources.list.d/gitea-mmainguy.sources` instead — use one file or the
|
||||
other, not both:
|
||||
|
||||
```
|
||||
Types: deb
|
||||
URIs: https://git.dasfad.com/api/packages/mmainguy/debian
|
||||
Suites: bookworm
|
||||
Components: main
|
||||
Signed-By: /etc/apt/keyrings/gitea-mmainguy.asc
|
||||
```
|
||||
|
||||
### 4. Credentials, if the Gitea owner is private
|
||||
|
||||
A public owner needs nothing here. Otherwise give apt a token with
|
||||
**package: Read** scope, kept out of the world-readable sources file:
|
||||
|
||||
```bash
|
||||
printf 'machine git.dasfad.com\nlogin mmainguy\npassword <read-only token>\n' \
|
||||
| sudo install -m 0600 /dev/stdin /etc/apt/auth.conf.d/gitea.conf
|
||||
```
|
||||
|
||||
### 5. Install
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
apt-cache policy cloudflared-tunnel # the candidate should come from git.dasfad.com
|
||||
sudo apt install cloudflared-tunnel
|
||||
```
|
||||
|
||||
The package depends on `cloudflared`. If you mirrored it
|
||||
(`./publish.sh --cloudflared`), that dependency resolves from this same repo and
|
||||
the machine needs no Cloudflare apt source at all. If you did not, add
|
||||
Cloudflare's own repo before installing.
|
||||
|
||||
Installing does not start a tunnel — `cloudflared-tunnel-setup` does:
|
||||
|
||||
```bash
|
||||
sudo cloudflared-tunnel-setup --hostname app.example.com --port 3000
|
||||
# or: --token <TUNNEL_TOKEN> or: --quick
|
||||
```
|
||||
|
||||
Later releases arrive with `sudo apt update && sudo apt upgrade`.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
| Symptom | Likely cause |
|
||||
|---|---|
|
||||
| `NO_PUBKEY` or `the following signatures couldn't be verified` | key missing or `signed-by=` path wrong — redo step 2 |
|
||||
| `404 Not Found` fetching `Release` | wrong owner or suite; check with `curl https://git.dasfad.com/api/packages/mmainguy/debian/dists/bookworm/Release` |
|
||||
| `401 Unauthorized` | private owner; add `/etc/apt/auth.conf.d/gitea.conf` (step 4) |
|
||||
| `Unable to locate package cloudflared-tunnel` | `apt update` not run since adding the source, or nothing published yet |
|
||||
| `cloudflared` has no installation candidate | the mirror is missing — run `./publish.sh --cloudflared` |
|
||||
| Installs fine but no tunnel | expected; run `cloudflared-tunnel-setup` |
|
||||
|
||||
### Removing the repo
|
||||
|
||||
```bash
|
||||
sudo rm -f /etc/apt/sources.list.d/gitea-mmainguy.list \
|
||||
/etc/apt/keyrings/gitea-mmainguy.asc \
|
||||
/etc/apt/auth.conf.d/gitea.conf
|
||||
sudo apt update
|
||||
```
|
||||
|
||||
## Changes from `setup-cloudflared.sh`
|
||||
|
||||
- **The tunnel service is now `cloudflared-tunnel.service`.** This avoids a
|
||||
|
||||
Loading…
Reference in New Issue
Block a user