Server Configuration

As Publii is a desktop application, it doesn't need to be connected to your website's server when you're making modifications or adding content; instead, whenever your changes are ready to go live, you'll just need to hit the Sync your website button in the bottom-left of the Publii app:

You can sync your website as often or as little as you wish. Publii generates your website files and, for deployment methods that support incremental uploads, uses file checksums to identify which files have changed since the previous sync. Unchanged files do not need to be uploaded again, so subsequent syncs will usually be faster. Before you can sync your site, though, you will need to enter your server details into the app. Don't worry if you do not have a server yet; you can still use Publii to create your website and add your server information later.

A small edit can affect more than one generated file. For example, changing CSS with CSS/JS versioning enabled updates the stylesheet URL in the pages that use it. Plugin changes can also affect pages across your site, while random related posts may change when the site is rebuilt. In these cases, Publii may need to upload many HTML files even though you have only edited one setting or post.

First steps

If you are setting a server up in Publii for the first time, you'll see a button marked Configure server instead of Sync your website. Clicking this will take you to the server configuration screen. Alternatively, you can click the Server option in the left sidebar to open this screen too.

If you haven't yet got a server, don't worry. You can continue to create content and customize your website locally in Publii and sync it later once your server is ready.

Before you get started with setting Publii up to sync to your server, you should make sure that you know which deployment method your hosting provider supports and have the information necessary to configure it in Publii. Details about the settings required for each deployment method are covered below. FTP and SFTP connections usually require the connection details supplied by your host, while services such as Amazon S3 require additional setup. You'll find links to detailed step-by-step guides below.

You can build your site's content before or after configuring your server; check the Content Creation section of this guide for information on creating posts, pages, tags and authors, inserting pictures and video, and more.

Choosing a server type

Upon clicking on the Configure server button, the first thing you'll see is a selection of server types for you to choose. Publii includes support for FTP and SFTP, Git, and several hosting and storage services, including Netlify, S3 compatible storage, GitLab Pages, GitHub Pages, and Google Cloud. There is also an option for Manual deployment, which exports the website files to your local machine.

Each server type offers its own benefits, depending on what you require from your site. We'll cover the settings for each server type below, with links to more in-depth guides. You can switch between server types later using the Change server type button. After choosing a server type, you will be taken to its configuration screen.

Server configuration options

Every server type includes two basic, universal options:

• Website URL - This is the public address where visitors will access your site, such as www.mysite.com. Select the appropriate protocol separately, usually https://. Publii also supports http://, file:///, dat://, hyper://, ipfs://, dweb://, and protocol-relative URLs beginning with //. If your website is hosted in a subdirectory, include it in the address, for example www.mysite.com/blog. Hosting services may provide their own generated domain; our guides for each server type cover where to find this. Make sure the selected protocol and the address you enter, including www if you use it, match your public website; a mismatch can stop images and styles from loading. See Fixing asset loading issues.
• Use relative URLs - This option generates links relative to the current page, using paths such as ./ and ../ instead of a fixed website address. The Website URL field is disabled while this option is enabled. Some features that require an absolute website address, including Open Graph tags, sitemaps, RSS feeds and JSON feeds, are also disabled.

As well as these base options, each deployment method has its own security, setup and sync requirements. Enter the configuration details for your selected method, then click Save settings to store them. For remote deployment methods, you can also click Test connection to check whether Publii can connect using the supplied details. Now let's look at each of the available methods and their settings:

FTP, FTPS and SFTP

FTP (File Transfer Protocol) is commonly available with traditional web hosting plans. Publii supports standard FTP, FTP secured with SSL/TLS (FTPS), and SFTP, which transfers files over SSH. Check with your hosting provider to find out which method and connection details you should use.

FTP uses an unencrypted connection, which means data sent over it, including your username and password, could be read by someone intercepting the connection. Use FTPS or SFTP whenever your host supports it.

Choose FTP or SFTP on the server selection screen. To use FTPS, choose FTP and enable Use FTP with SSL/TLS. The available options depend on the selected connection and authentication method:

• Port - Sets the port that Publii should connect through. This is usually 21 for FTP or explicit FTPS, and 22 for SFTP, but use the port supplied by your hosting provider.
• Server - Enter the server hostname or IP address supplied by your host, such as ftp.example.com. Do not include a protocol prefix such as ftp:// or https://.
• Username - The username for your FTP or SFTP account.
• Authentication method - For SFTP, choose whether to connect using a password or a key file.
• Password - The password for your account when using password authentication. This field is hidden when Always ask for password is enabled.
• Your key (SFTP with key only) - Define the path to your SFTP private key here. Clicking on the field will open the file picker; navigate to and select your key to continue.
• Key passphrase (SFTP with key only) - Enter the passphrase for your private key if it has one.
• Always ask for password - When this option is enabled, you will be required to enter your account password when syncing your site.
• Certificates (FTPS only) - The Require a valid certificate for connection option controls whether Publii requires a valid server certificate when connecting.
• Remote path - The destination folder on your server where Publii should upload the website files, such as /public_html/ or a subfolder such as /public_html/blog/. The correct path depends on the folders your account can access; your hosting provider can confirm it.

S3 compatible storage

Publii supports Amazon S3 by default and can also connect to other S3 compatible storage providers using a custom endpoint. Amazon S3 (Simple Storage Service) provides online storage for files, which can be configured for static website hosting. When S3 compatible storage is selected, the following options will be available. For a more in-depth tutorial, see Setting up Amazon S3 Hosting.

• Use a custom S3 provider - Enable this option to connect to an alternative S3 compatible provider, then enter its endpoint.
• Access ID - Enter the access key ID for credentials with permission to access your website's bucket.
• Secret key - Enter the secret access key associated with the access key ID.
• Bucket - Add your case-sensitive bucket name to this field.
• Region - Choose the same region you have set for your bucket. When using a custom provider, enter the region required by that provider.
• Prefix - Enter a prefix here, such as blog/, to upload the website files under that path in your bucket.
• Cache-Control header for HTML files - Sets the Cache-Control HTTP header for HTML files. Using no-cache, no-store prevents browsers from storing these responses for reuse, which is useful for content that changes frequently.
• Cache-Control header for other files - Sets the Cache-Control header for other file types, including images, CSS and JavaScript. A value such as public, max-age=2592000 allows these files to be cached for 30 days. Keep in mind that visitors may continue to see a cached file during that period if its URL remains unchanged.
• ACL - Select the predefined access permissions, known as a canned ACL, appropriate for your bucket and provider.

Git

The Git deployment method publishes your generated website files to a Git repository. Use this when your hosting setup deploys a website from a repository. The repository and hosting service must be configured to publish the branch you select.

The following options are available:

• Repository URL - Enter the HTTPS URL used to access your Git repository.
• Branch - Enter the branch that should receive your generated website files.
• Username - Enter the username required by your Git provider.
• Password / Token - Enter your access token or password, depending on your provider's authentication requirements.
• Commit author - Enter the author name to use for commits created by Publii.
• Commit author email - Enter the email address to associate with those commits.
• Commit message - Set the message Publii should use when committing your website files.

If your hosting provider requires a CNAME file for a custom domain, add it to your website's root files using the File Manager.

GitHub Pages

GitHub Pages provides website hosting for projects, organizations and personal sites. When GitHub Pages is selected, the following options will be available. Full details on setting up and configuring GitHub Pages for your Publii site can be found in the GitHub Pages section of this guide. You can also keep the repository private and serve the site through Cloudflare Pages.

• API server - By default, this field is already completed with the standard GitHub API server. If you are using your own GitHub instance, enter its API server here.
• Username/Organization - Enter your GitHub username or organization here.
• Repository - Enter your repository name here.
• Branch - Enter the branch that should receive your generated website files. Configure GitHub Pages or your hosting service to publish from this branch.
• Folder - Optionally enter a subfolder within the selected branch, such as docs or public. Leave this field empty to upload to the repository root. When a subfolder is selected, Publii leaves files outside it unchanged during synchronization.
• Token - Enter an access token with the permissions required to update the repository.
• Parallel uploads - Defaults to 1. Sets the number of upload operations Publii can run at the same time. Higher values may make uploads faster, but can also cause connection errors or trigger API rate limits.
• API rate limiting - Disable this option only if you are using GitHub Enterprise with API rate limiting disabled. Otherwise, disabling it can cause deployment errors.

When GitHub Pages is configured to deploy from a branch, its publishing folder must be the repository root or /docs. To use /docs, enter docs in Publii's Folder field and select /docs in your repository's Pages settings. Other subfolders can be used with hosting services such as Cloudflare Pages, provided the service is configured to publish from that folder.

Changing the publishing folder: Moving from the repository root to a subfolder, or from one subfolder to another, leaves the previous website files in place; remove them manually if they are no longer needed. If you leave Folder empty, Publii manages the entire selected branch and removes files that are not part of the generated website during synchronization. This also applies when switching from a subfolder back to the repository root. Publii displays a warning when you save a change to this setting.

Before uploading, Publii checks for files exceeding this integration's 30 MB per-file upload limit. If any are found, Publii lists them so you can reduce their size or remove them from your website before trying again.

Once the server options are set, click Save settings to store the details. You can also click Test connection to check whether Publii can connect using them.

Netlify

Netlify is a website hosting service that can receive your generated website directly from Publii. If Netlify is selected, the following options will be available. Full step-by-step instructions for setting up Netlify for use with Publii can be found in the Netlify section of this guide.

• Site ID - Enter the identifier for your website from its settings in Netlify.
• Netlify token - Enter an access token generated in your Netlify account.

Google Cloud

Publii can upload your generated website to a Google Cloud Storage bucket configured for website hosting. If Google Cloud is selected, the following options will be available. An in-depth setup guide can be found in the Google Cloud section of this guide.

• Your JSON key - Select the JSON file containing the credentials Publii should use to access your Google Cloud bucket.
• Bucket - Enter your Google Cloud bucket name here.
• Prefix - Enter a prefix to upload your website under a particular path in the bucket. For example, entering blog places the website files under that prefix. Do not start the prefix with a slash.

GitLab Pages

GitLab Pages provides website hosting for projects created on GitLab. If GitLab Pages is selected, the following options will be available. If you need help preparing your GitLab project for use with Publii, see the step-by-step GitLab Pages article.

• Server - The address of your GitLab instance. Leave the default value unless you are using a different instance.
• Certificates - The Require a valid certificate for connection option controls whether Publii requires a valid server certificate when connecting.
• Repository - Enter the full project path, including the user or group and any subgroups, such as username/project or group/subgroup/project. Use the path exactly as it appears in GitLab; this field is case-sensitive.
• Branch - Enter the branch that should receive your website files. Your GitLab Pages configuration must publish from the appropriate branch.
• Token - Enter an access token with the permissions required to update your project. For a fine-grained token, use the permissions listed below.

Fine-grained GitLab tokens

To use a fine-grained personal access token, you need Publii 0.48.2 or later. When creating a token in GitLab, limit its access to the project you want to publish to or the group containing that project. Under Add resource permissions, select the Group and project tab and grant these minimum permissions:

These permissions are sufficient when the Repository field contains the full project path. Entering only the project name makes Publii search for the project and requires the broader Project → Read permission in the User tab.

The token owner must also have permission to push to the selected branch. If the branch is protected, check its push permissions; the token's permissions do not override branch protection rules. The Code → Read and Code → Push permissions are not required for the GitLab Pages integration, which uses GitLab's REST API.

Manual upload

Though Publii is designed to manage website updates and syncs automatically, you may not have direct access to your server, may prefer to upload your website manually, or may simply wish to export your site for later deployment. In these cases, choose Manual deployment to export the generated website in a format of your choice.

The following options are available:

• Output type - Choose an uncompressed folder, a ZIP archive or a TAR archive. Publii creates the selected output when you sync your website. Once the export is complete, you can open its location.
• Output directory - Sets where the exported folder or archive should be saved. Click the field to choose an existing folder, or leave it blank to use your site's folder inside the Publii sites location.

When you choose a custom output directory, Publii creates a folder or archive named after your site with a -files suffix. An existing export with the same name is replaced during the next export. Manual deployment generates the files locally; you will need to upload them to your hosting provider yourself.