141 lines
4.4 KiB
Markdown
141 lines
4.4 KiB
Markdown
# Portfolio Gitea Runner
|
|
|
|
Machine-specific Gitea Actions runner and Caddy integration for the portfolio
|
|
host. The reusable `gitea-deployment` repository remains unchanged.
|
|
|
|
The runner is intentionally repository-scoped and has access to the host Docker
|
|
daemon. Only trusted workflows may use its `portfolio-ci` label.
|
|
|
|
## Server layout
|
|
|
|
```text
|
|
~/gitea-deployment/ Generic reusable Gitea checkout
|
|
~/caddy-deployment/ Shared Caddy deployment
|
|
~/portfolio-gitea-runner/ This repository
|
|
```
|
|
|
|
`scripts/gitea-compose.sh` combines the generic Compose file with
|
|
`gitea.caddy.yaml`. The override connects Gitea to `caddy_proxy` and puts the
|
|
generic Nginx and Certbot services behind the inactive `bundled-proxy` profile.
|
|
|
|
## Migrate the existing server checkout
|
|
|
|
Clone this repository first, then validate and activate the external override
|
|
before restoring files in the generic checkout:
|
|
|
|
```bash
|
|
cd ~
|
|
git clone https://git.amiirkhl.ir/amiirkhl/portfolio-gitea-runner.git
|
|
cd ~/portfolio-gitea-runner
|
|
bash scripts/gitea-compose.sh config --quiet
|
|
bash scripts/gitea-compose.sh up -d --remove-orphans
|
|
curl -fsS https://git.amiirkhl.ir/api/healthz
|
|
```
|
|
|
|
After Gitea is healthy through Caddy, preserve the obsolete generated Nginx
|
|
directory outside the generic checkout and restore only the known server-local
|
|
paths:
|
|
|
|
```bash
|
|
cd ~/gitea-deployment
|
|
git status --short
|
|
git diff -- docker-compose.yml
|
|
git diff --cached
|
|
|
|
git restore --staged -- nginx/conf.d/gitea.conf 2>/dev/null || true
|
|
mkdir -p ~/portfolio-gitea-runner/server-state
|
|
if [[ -d nginx ]]; then
|
|
mv nginx ~/portfolio-gitea-runner/server-state/legacy-nginx
|
|
fi
|
|
git restore --source=HEAD --staged --worktree -- docker-compose.yml
|
|
|
|
test -z "$(git status --porcelain)"
|
|
```
|
|
|
|
The last command must succeed. From this point onward, use
|
|
`scripts/gitea-compose.sh` for this server instead of running Compose directly
|
|
inside the generic checkout.
|
|
|
|
## Install the runner
|
|
|
|
Create a repository runner token under the portfolio repository's
|
|
**Settings > Actions > Runners**, then configure the server:
|
|
|
|
```bash
|
|
git clone https://git.amiirkhl.ir/amiirkhl/portfolio-gitea-runner.git
|
|
cd portfolio-gitea-runner
|
|
cp .env.example .env
|
|
chmod 600 .env
|
|
nano .env
|
|
bash scripts/setup-runner.sh
|
|
docker compose logs --follow runner
|
|
```
|
|
|
|
Use these values in `.env`:
|
|
|
|
```dotenv
|
|
GITEA_INSTANCE_URL=https://git.amiirkhl.ir
|
|
GITEA_RUNNER_REGISTRATION_TOKEN=the-repository-runner-token
|
|
RUNNER_DATA_PATH=./data
|
|
```
|
|
|
|
After `/data/.runner` is created, clear the reusable token in `.env` and
|
|
recreate the runner:
|
|
|
|
```bash
|
|
sed -i 's/^GITEA_RUNNER_REGISTRATION_TOKEN=.*/GITEA_RUNNER_REGISTRATION_TOKEN=/' .env
|
|
docker compose up -d --force-recreate runner
|
|
bash scripts/check-runner.sh
|
|
```
|
|
|
|
The `portfolio-runner-docker-config` volume retains the Buildx builder
|
|
definition between job containers. The BuildKit container retains npm and
|
|
Next.js cache mounts. Capacity is limited to one job for the shared 2-core,
|
|
4-GB host.
|
|
|
|
## Manage the Caddy-backed Gitea instance
|
|
|
|
Always invoke the generic deployment through the wrapper on this server:
|
|
|
|
```bash
|
|
bash scripts/gitea-compose.sh config --quiet
|
|
bash scripts/gitea-compose.sh up -d --remove-orphans
|
|
bash scripts/gitea-compose.sh ps
|
|
bash scripts/gitea-compose.sh logs --tail=100 gitea
|
|
```
|
|
|
|
Set `GITEA_DEPLOYMENT_PATH` only if the generic checkout is not located at
|
|
`~/gitea-deployment`.
|
|
|
|
## Update and back up Gitea
|
|
|
|
Pull repository changes while Gitea is still running. Before changing the Gitea
|
|
image, stop the application and back up PostgreSQL, `/data`, and the generic
|
|
deployment's `.env`. Use the wrapper for every subsequent Compose operation so
|
|
the Caddy override is always active.
|
|
|
|
```bash
|
|
bash scripts/gitea-compose.sh pull gitea
|
|
bash scripts/gitea-compose.sh stop gitea
|
|
bash scripts/gitea-compose.sh up -d --remove-orphans
|
|
bash scripts/gitea-compose.sh exec -u git gitea gitea doctor check
|
|
curl -fsS https://git.amiirkhl.ir/api/healthz
|
|
```
|
|
|
|
Restoring an older image after a minor-version database migration may require
|
|
restoring the database and data backup as well.
|
|
|
|
## Inspect and troubleshoot
|
|
|
|
```bash
|
|
bash scripts/inspect-runner.sh | tee runner-inspection.log
|
|
docker run --rm \
|
|
-v /var/run/docker.sock:/var/run/docker.sock \
|
|
-v portfolio-runner-docker-config:/root/.docker \
|
|
portfolio-runner-job:node22 \
|
|
docker buildx inspect portfolio-builder
|
|
```
|
|
|
|
The first portfolio pipeline run creates `portfolio-builder`. Later runs must
|
|
reuse the same builder and cached npm/Next.js layers.
|