Deployment

YiiPress generates static HTML, CSS, JavaScript, feeds, and metadata files during the build process, eliminating the need for YiiPress or a PHP runtime in production. Any static file hosting service can serve the generated output/ directory.

The recommended build tool is the static yiipress binary:

./yiipress build --content-dir=content

The generated files will be placed in the output directory (default: output). You can then host this directory with any static file server or hosting service.

Build Tool Options

Prefer these options in this order:

Static binary — best default for local builds and most CI systems. It has the runtime embedded and does not require PHP or Composer.
YiiPress GitHub Action — best default for GitHub-hosted CI. It downloads the Linux binary and runs the build.
PHAR or source checkout — intended for contributors or environments that already provide PHP 8.5 and required extensions.

Any Web Host (FTP / cPanel)

The simplest deployment option is to upload the build output directly to your hosting provider's webroot:

Build your site: ./yiipress build --content-dir=content
Open your hosting control panel or FTP client.
Upload the entire contents of the output directory to your server's webroot folder. This folder is commonly named www, public_html, htdocs, or html depending on your provider.
Your site is live. The server only serves static files.

GitHub Pages

GitHub Pages hosts static sites directly from a GitHub repository for free. The recommended approach is to use a GitHub Actions workflow that builds the site and publishes it to the github-pages environment on every push.

How GitHub Pages works

GitHub Pages serves the files uploaded to its github-pages deployment environment. A workflow uploads the build artifact using actions/upload-pages-artifact and then deploys it using actions/deploy-pages.

Example GitHub Actions workflow

Create .github/workflows/deploy.yml in your repository:

name: Build and Deploy to GitHub Pages

on:
  push:
    branches:
      - master
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Build YiiPress site
        uses: yiipress/engine/.github/actions/build@X.Y.Z
        with:
          version: X.Y.Z

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Enable GitHub Pages in your repository settings: go to Settings → Pages and set the source to GitHub Actions.

Tip: Replace X.Y.Z with a real YiiPress version tag for reproducible, stable builds. The action builds to _site by default for GitHub Pages. See GitHub Actions for custom output directories and other inputs.

For project sites such as https://user.github.io/project/, set base_url to the full deployed URL including the project path. YiiPress uses that path when rendering root-relative redirect targets, so redirect_to: /blog/ points to /project/blog/ in browser-facing redirect HTML. Internal links generated by built-in templates and processors are emitted relative to each page, while feeds, sitemaps, canonical URLs, and redirect pages use absolute or browser-facing URLs with the configured project path. Custom templates should use the $url() helper for internal links and Asset::url() for copied assets.

Real-world example: YiiPress documentation is built from the nightly binary image after the package workflow succeeds — see .github/workflows/build-docs.yml in this repository. Site repositories should use the release action above with a fixed version for production or version: nightly to test the newest immutable nightly prerelease.

Cloudflare Pages

Cloudflare Pages offers a free, globally distributed CDN for static sites with automatic deployments from Git.

Push your project to a GitHub or GitLab repository.
In the Cloudflare dashboard, go to Workers & Pages → Create application → Pages → Connect to Git.

Select your repository and configure the build settings:

Install command:

curl -fsSLO https://github.com/yiipress/engine/releases/download/X.Y.Z/yiipress-linux-amd64.tar.gz && curl -fsSLO https://github.com/yiipress/engine/releases/download/X.Y.Z/SHA256SUMS && checksum="$(awk '$2 ~ /(^|\/)yiipress-linux-amd64\.tar\.gz$/ { print $1; exit }' SHA256SUMS)" && test -n "$checksum" && printf '%s  yiipress-linux-amd64.tar.gz\n' "$checksum" | sha256sum -c - && tar -xzf yiipress-linux-amd64.tar.gz && chmod +x yiipress

Build command:./yiipress build --output-dir=_site --no-cache
Build output directory:_site

Click Save and Deploy.

Cloudflare Pages will rebuild and redeploy your site automatically on every push to the configured branch. Replace X.Y.Z with a fixed YiiPress release.

Alternative: If you prefer, build the site locally or in your own CI pipeline, then deploy the _site/ directory using the Wrangler CLI:
npx wrangler pages deploy _site --project-name=my-site

Minimal Docker Image

You can package your generated static site into a tiny Docker image using lipanski/docker-static-website. This image is based on BusyBox httpd and is only a few megabytes in size, making it useful for self-hosted or containerized environments.

Build the site first:

./yiipress build --output-dir=_site --no-cache

Then create a Dockerfile in your project root:

FROM lipanski/docker-static-website:latest

COPY _site .

Build and run the image:

docker build -t my-site .
docker run -p 3000:3000 my-site

Your site will be available at http://localhost:3000.

To deploy, push the image to any container registry and run it on any platform that supports Docker — a VPS, Fly.io, Railway, Render, or any Kubernetes cluster.

Packaging details for the YiiPress executable, PHAR, and distroless image are covered in Binaries, PHAR, Docker.