Pages Platform

Static site hosting at pages.kotel.app/{site-name}/

Overview

The pages platform serves static sites via Caddy at pages.kotel.app/{site-name}/. Sites are deployed using a Gitea Actions composite action that rsyncs files to the server over SSH.

Prerequisites

Gitea Actions enabled on your repository
PAGES_SSH_KEY secret configured in the repository (SSH private key authorized on the pages server)

Action Reference

The composite action is referenced in workflows as:

uses: https://gitea.kotel.app/hay-kot/infra/actions/deploy-pages@main

Inputs

Input	Required	Default	Description
`site-name`	Yes	-	Name of the site, used as the URL path segment
`source-dir`	Yes	-	Local directory containing the built site files
`ssh-key`	Yes	-	SSH private key for authenticating with the pages server
`spa`	No	`false`	Enable SPA mode (all sub-routes serve index.html)

Base Path Configuration

Sites are served under a sub-path, so builds must set the base path correctly.

Framework	Configuration
Plain HTML	Use relative paths for assets (e.g., `./style.css`)
Vite	`base: "/site-name/"` in `vite.config.js`
Hugo	`baseURL: "https://pages.kotel.app/site-name/"`
Next.js	`basePath: "/site-name"` in `next.config.js`

Examples

Static Site (no build step)

Deploy a directory of static files directly.

name: Deploy Site

on:
  push:
    branches: [main]
    paths: ["site/**"]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: https://gitea.kotel.app/hay-kot/infra/actions/deploy-pages@main
        with:
          site-name: my-site
          source-dir: site
          ssh-key: ${{ secrets.PAGES_SSH_KEY }}

SPA Mode

For single-page applications, enable SPA mode so all sub-routes serve index.html.

      - uses: https://gitea.kotel.app/hay-kot/infra/actions/deploy-pages@main
        with:
          site-name: my-app
          source-dir: dist
          spa: "true"
          ssh-key: ${{ secrets.PAGES_SSH_KEY }}

With Build Step

Run a build before deploying the output directory.

name: Build and Deploy

on:
  push:
    branches: [main]
    paths: ["src/**", "package.json"]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - run: npm ci && npm run build

      - uses: https://gitea.kotel.app/hay-kot/infra/actions/deploy-pages@main
        with:
          site-name: my-app
          source-dir: dist
          ssh-key: ${{ secrets.PAGES_SSH_KEY }}