feat: add dedicated portfolio Gitea runner

README.md

@@ -0,0 +1,140 @@
+# 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.