Skip to content

deployment.md

Latest commit

 

History

History
146 lines (101 loc) · 6.65 KB

deployment.md

File metadata and controls

146 lines (101 loc) · 6.65 KB

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:

  1. Static binary — best default for local builds and most CI systems. It has the runtime embedded and does not require PHP or Composer.
  2. YiiPress GitHub Action — best default for GitHub-hosted CI. It downloads the Linux binary and runs the build.
  3. 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:

  1. Build your site: ./yiipress build --content-dir=content
  2. Open your hosting control panel or FTP client.
  3. 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.
  4. 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.

  1. Push your project to a GitHub or GitLab repository.
  2. In the Cloudflare dashboard, go to Workers & Pages → Create application → Pages → Connect to Git.
  3. 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
  4. 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.