Migrating From Wagtail To Astro (4): Deployment
· 11 min read · Views --
Last updated on

Migrating From Wagtail To Astro (4): Deployment

Author: Alex Xiang

Blogging

Migrating From Wagtail To Astro (4): Deployment

This is the fourth article in the Wagtail-to-Astro series. It explains how to deploy the static site generated by Astro, while also considering ICP record information and HTTPS.

Local Build

From the project root:

cd astro-site
pnpm build

By default, Astro generates a static site into the dist/ directory, including:

  • index.html files for all pages.
  • Static assets such as JavaScript, CSS, and fonts.
  • Files under public/, such as images and favicon files, copied into the corresponding paths under dist/.

After building, run pnpm preview locally to confirm that there are no obvious 404s and that assets load correctly.

Deploying To A Server

Upload Options

Common options include:

  • rsync / scp: Sync the entire dist/ directory to a server directory, such as /work/zicode-astro, and wrap the command in a script or Makefile.
  • CI/CD: Configure GitHub Actions or GitLab CI to run pnpm build after pushes, then upload dist/ to the server or object storage.

This site uses a deployment script plus SFTP/SCP. The repository contains scripts/deploy_astro.py, which reads configuration such as server address, target path, and authentication method, then uploads local dist/ to the remote directory.

Directory And Web Root

  • Choose a directory on the server as the Astro site root, for example /work/zicode-astro.
  • Configure Nginx or another web server to use that directory as root, and add try_files or a fallback rule so paths such as /blog/xxx/ return the corresponding index.html.

Example:

root /work/zicode-astro;
index index.html;
location / {
    try_files $uri $uri/ $uri/index.html =404;
}

Then /blog/wagtail-to-astro-1-why/ maps to dist/blog/wagtail-to-astro-1-why/index.html. If Astro uses trailingSlash: 'always', the generated directory structure naturally matches this setup.

Permissions And Ownership

Make sure the web process, such as www-data or nginx, can read the directory. If files are uploaded over SSH, you may need to adjust ownership with chown after upload.

ICP Record And HTTPS

ICP Record

If the site is hosted in mainland China, it needs an ICP record. After approval, show the ICP record number in the footer and link it to the official MIIT site, for example:

This site has added the link in the Footer component.

HTTPS

Use HTTPS for the whole site:

  • Configure SSL in Nginx, for example with Let’s Encrypt, and redirect HTTP to HTTPS.
  • If page links are relative, no content change is needed. If site or canonical URLs are configured, make sure they start with https://.

Release Flow Summary

  1. Run pnpm build locally or in CI.
  2. Upload dist/ to the server target directory.
  3. Confirm that Nginx points to that directory and that try_files works.
  4. Check ICP record display and HTTPS. Add 301 redirects from old Wagtail URLs if needed.

Before the first launch, it is useful to run chmod -R o+r on the server directory, or make the web user the owner, to avoid 403 errors caused by permissions. If CI/CD is used, ensure the pipeline has permission to write to the target directory or upload through an SSH key. After these steps, the Astro version of the blog can serve production traffic.

Series: Part 1: Why migrate and how I chose · Part 2: The main phases · Part 3: Adding new posts · Part 4: Deployment · Part 5: Data sync and scripting · Part 6: Theme and feature polish

More in this column

View all posts in "Wagtail To Astro"