# 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.