# Deploy a Publii site

> Publish a Publii blog on your own domain: render it with manual deployment, add the trailing-slash setting for Pretty URLs, keep the site folder out of iCloud, then deploy from your computer or the portal.

Source: https://docs.evolvingedge.ai/static-sites/publii/

Publish a Publii site on your own domain. Publii renders the site to a folder on your computer, and you deploy that folder from the command line or the portal.

| | |
|---|---|
| Build | **Sync your website** in Publii, with the server set to **Manual deployment** |
| Output folder | `<your site>-files`, inside the output directory you choose |
| Settings you need | Your website URL set to your domain |
| Routing | Trailing slash, if **Pretty URLs** is on |

## Before you begin

You need:

- A Publii site that renders on your computer.
- An Evolving Edge account that can deploy workloads. See [Getting Started](https://docs.evolvingedge.ai/customer-getting-started/).
- A project in the portal, and its project ID (it starts with `proj_`).
- A deploy token from the portal, under **Workload → Deploy Tokens**, with `workload:write`. Scope it to the project. See [Deploy tokens](https://docs.evolvingedge.ai/cli/#deploy-tokens).
- The domain you want to serve the site on, for example `www.example.com`, and access to its DNS settings.
- Node.js 22.12 or later, on Windows (x64), macOS, or Linux (x64 or arm64), to deploy from your computer. To deploy from the portal instead, you don't need Node.js.

## 1. Keep the site folder out of iCloud

On a Mac, Publii keeps its sites under `~/Documents/Publii` by default. If iCloud's **Desktop & Documents** sync is on, iCloud syncs every file Publii renders, and two things go wrong:

- **Packaging slows to a crawl.** macOS checks each file with iCloud as it's read. A 419 MB blog took minutes to package with almost no CPU in use.
- **Numbered copies appear in the output.** When Publii rewrites a file while iCloud is syncing it, iCloud can keep both, as `photo 2.webp` beside `photo.webp`. In one site, 964 of 2,073 rendered files were copies like this, and they'd all be deployed.

Quit Publii, move the `Publii` folder somewhere iCloud doesn't sync, for example `~/Sites/Publii`, and choose the new location in Publii's settings. The same applies to Dropbox, OneDrive and other sync folders.

## 2. Render with manual deployment

With manual deployment, Publii renders the whole site to a folder on your computer, and uploads nothing.

1. In Publii, open **Server** and choose **Manual deployment**.

   ![Publii's Select server type screen, with Server selected in the sidebar and the Manual deployment option highlighted](https://docs.evolvingedge.ai/images/static-sites/publii/server-type.png)

2. On the **Manual upload** settings, set:
   - **Website URL:** the address visitors use, for example `https://www.example.com`, with or without `www` exactly as you'll serve it. Publii writes it into feeds, sitemaps, Open Graph tags and canonical links.
   - **Use relative URLs:** off. While it's on, Publii leaves out Open Graph tags, sitemaps, and RSS and JSON feeds.
   - **Output type:** **Uncompressed folder**.
   - **Output directory:** a folder outside iCloud (step 1). Publii writes the site to a folder named after your site inside it, for example `my-blog-files`, and replaces it on every render.

   Then **Save settings**.

   ![Publii's Manual upload settings: Website URL, Use relative URLs off, Output type Uncompressed folder, and the Output directory highlighted](https://docs.evolvingedge.ai/images/static-sites/publii/manual-upload-settings.png)

3. Click **Sync your website**. With manual deployment, that renders the site to the output folder. Check that the folder holds `index.html` at its top level.

## 3. Turn on the trailing slash for Pretty URLs

Publii's **Pretty URLs** setting is under **Site settings → Advanced options → URLs** as **Use pretty URLs**. Leave **Always add index.html in URLs**, just below it, off: it's only for servers that can't serve a folder's `index.html`.

![Publii's Site settings, Advanced options, URLs: Use pretty URLs switched on and highlighted, and Always add index.html in URLs off](https://docs.evolvingedge.ai/images/static-sites/publii/pretty-urls.png)

With pretty URLs on, Publii writes each post as a folder (`my-post/index.html`, served at `/my-post/`). Without a setting, `/my-post` with no slash is a 404. Two ways to fix it:

- **From the command line:** add `--trailing-slash` to every deploy (step 5).
- **For every deploy, including from the portal:** add a [`_redirects`](https://docs.evolvingedge.ai/redirects/) file to Publii's **root directory**, which Publii copies to the top of every render:

  1. In Publii, open **Tools**, then **Files**, and choose **root directory**.
  2. Click **Add new file**, name it `_redirects`, with no extension, and give it this one line:

     ```text
     # ee:trailing-slash on
     ```

     Or create the file elsewhere and add it with **Upload files**.
  3. Sync your website, then check that `_redirects` is in the output folder.

  ![Publii's Files tool under Tools, showing the root directory with the _redirects file in it](https://docs.evolvingedge.ai/images/static-sites/publii/files-root-directory.png)

With pretty URLs off (`my-post.html`), skip this step.

## 4. Claim your domain

Only the project that claimed a domain can deploy to it. In the portal, or from the command line:

```sh
export EE_CDN_TOKEN=<your deploy token>
npx -p @evolving-edge/ee-cdn-cli ee-domain claim www.example.com --project proj_abc123 --wait
```

It prints a TXT record and a CNAME record to add at your DNS provider, then waits until the domain is active. See [Custom domains](https://docs.evolvingedge.ai/custom-domains/) for the portal steps, root domains and Cloudflare.

**Moving a live blog?** The claim becomes active once its certificate is issued, and that needs the CNAME to point at Evolving Edge already. Pointing the CNAME at Evolving Edge moves your visitors before your first deploy. So have everything ready first:

1. Render the site and run a [dry run](#5-deploy-from-your-computer).
2. Add the TXT record, then the CNAME record.
3. Deploy as soon as the claim is active.

Until that first deploy finishes, visitors get a 404. For a site of a few hundred megabytes, that's a few minutes.

## 5. Deploy from your computer

Install the command line tool once:

```sh
npm install -g @evolving-edge/ee-cdn-cli
```

That gives you `ee-deploy` and `ee-domain`. Run them from a folder of your own, not the output folder: the first deploy writes `.ee-builder-lock.json` where you run it.

Check the package first with a dry run, which packages the site without uploading it:

```sh
export EE_CDN_TOKEN=<your deploy token>
export EE_CDN_PROJECT_ID=proj_abc123
ee-deploy ~/"Sites/blog-output/my-blog-files" --domain www.example.com --trailing-slash --dry-run
```

Then deploy:

```sh
ee-deploy ~/"Sites/blog-output/my-blog-files" --domain www.example.com --trailing-slash
```

- Use your own output folder's path. Keep a leading `~` outside the quotes: the shell doesn't expand it inside them.
- Leave out `--trailing-slash` if `_redirects` is in Publii's root directory already, or if Pretty URLs is off.
- A dry run leaves the package in your temp folder, and prints where.
- Each deploy replaces the whole site on that domain. Allow up to about 90 seconds for it to reach every node.

## 6. Deploy from the portal

In your project, upload the contents of the output folder (Publii's `index.html` at the top), then create a deployment target with your domain and deploy. A package can be up to [1 GiB](https://docs.evolvingedge.ai/cli/#size-limit). A blog with hundreds of large photos takes several minutes to package. For pretty URLs, add `_redirects` to Publii's root directory (step 3): the portal has no `--trailing-slash` option.

## Redeploys and images

- **Every new post re-uploads the whole site.** The package changes with any change to the site, so a new post on a 400 MB blog uploads 400 MB again. Deploying unchanged content uploads nothing. See [Redeploys and rollbacks](https://docs.evolvingedge.ai/cli/#redeploys-and-rollbacks).
- **Photos take most of the room.** Publii already makes resized copies for responsive images. To make the package smaller, see [Images](https://docs.evolvingedge.ai/image-conversion/), which can convert photos to WebP or AVIF and scale down wide ones while packaging.

## What doesn't carry over

- **Publii's own deployment targets.** Publii can upload to FTP, SFTP, Amazon S3, Netlify, GitHub Pages and others, but has no Evolving Edge target. Use manual deployment and `ee-deploy`, or the portal.
- **Subfolder sites.** A site owns its whole domain.

## Troubleshooting

| What you see | Why | What to do |
|---|---|---|
| Packaging takes many minutes with almost no CPU in use | The site folder is in iCloud or another sync folder | [Move it out](#1-keep-the-site-folder-out-of-icloud), render again |
| Feeds, the sitemap or link previews are missing | **Use relative URLs** is on | Turn it off in the Manual upload settings, then sync again |
| Files named like `photo 2.webp` in the output | A sync service kept extra copies | Move the site out of the sync folder, empty the output folder, render again |
| `/my-post` is a 404 but `/my-post/` works | Pretty URLs without the trailing-slash setting | Deploy with `--trailing-slash`, or add `_redirects` to Publii's root directory (**Tools → Files**) |
| `ee-deploy: --domain is required` | A domain is needed even for a dry run | Pass `--domain` with your real domain |
| `ee-deploy` can't find the folder | `~` inside quotes | Write `~/"…"`, with the `~` outside the quotes |
| The deploy is refused for your domain | The domain isn't claimed for this project, or the claim isn't active yet | [Claim it](#4-claim-your-domain) and wait until it's active |
| `No deploy token` | `EE_CDN_TOKEN` isn't set | Export it in the same terminal |

More in the [command line troubleshooting](https://docs.evolvingedge.ai/cli/#troubleshooting).
