~/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:

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:

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:

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:

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:

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