Production deployment¶

Available workflows¶

The toolchain provides the following workflows under the directory .github/workflows:

Installation¶

To install the workflows:

1. Copy the workflows named docs-*.yaml from .github/workflows to your project. The project’s directory structure should look like the following:

   project-name/
     ├── .github/
     |   ├── workflows/
     |   |   ├── docs-pages.yaml
     |   |   ├── docs-pr.yaml
   

2. If the default branch is not master or the docs are not located under the docs folder, modify the workflows to align with the project configuration. For example:

   on:
   push:
       branches:
       - master # edit this line
       paths:
       - "docs/**" # edit this line
   

3. In the repository’s Settings, navigate to the Pages section and select GitHub Actions as the deployment source.

   

4. Commit and push the changes to your GitHub repository. Make sure to push these changes to the default branch.

Once you push the workflows to the remote repository default branch, GitHub might take a couple of minutes to build and publish the site.

If everything goes well, you will see the docs published under https://scylladb.github.io/<repository-slug>.

Setting up a custom domain¶

Follow the following steps to set up a custom domain:

1. In the domain’s DNS configuration, create a new CNAME record that points <custom-sudomain>.scylladb.com to scylladb.github.io.

2. Change html_baseurl setting in conf.py for the desired sub-domain name. For instance, we will use sphinx-theme.scylladb.com.

3. Commit and push the changes to your GitHub repository. Make sure to push these changes to the default branch.

4. In the repository’s Settings, navigate to the Pages section and make sure the custom domain name is set under Custom domain and Enforce HTTPS is enabled.

1. Verify the domain name to restrict its usage only on ScyllaDB organization repositories. To do so, follow the steps in Verifying your domain with GitHub.

2. Once the DNS changes propagate (<24 h), the docs will be accessible from the custom domain name.

Reading error messages¶

Docs builds usually fail when there is a critical error or warning in the documenation syntax.

To get the specific error message:

1. Hover the that you will see next to the commit message, and click on Details.

   

2. Search for “warning” and “error” in the box you will find at the top right of the screen.

   

You should see the error messages highlighted.

Publishing the docs manually¶

If you need to manually trigger a documentation build and publish the latest changes, follow the steps below. This might be necessary if automatic triggers fail.

To manually rerun the last build, follow these steps:

1. Navigate to your repository’s Actions tab on GitHub.

2. In the list of workflows, locate and select the docs-pages.yaml workflow.

3. On the workflow’s page, click the Run workflow button. For more details, see Manually running a workflow.

4. IMPORTANT: When prompted, ensure you select the default branch (usually master or main). This ensures the workflow runs using the latest version of the configuration file, which contains information about which branches to build.

5. Confirm the action and wait for the workflow to complete.

Disabling GitHub Pages¶

To disable the docs deployment temporarily:

1. Delete the workflows from .github/workflows.

2. Disable GitHub Pages from the repository settings. For more information, see Unpublishing a GitHub Pages Site.