# Production deployment

We use GitHub Pages and GitHub Actions to make the documentation publicly available.

On this page, you will learn:

- How to deploy to GitHub Pages.
- How to set up a custom domain.
- How to read build error messages.
- How to re-run a workflow.
- How to disable GitHub Pages.

<a id="available-workflows"></a>

## Available workflows

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

| Filename                     | Description                                                                                                                                                                                                                       |
|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `docs-pages.yaml`            | Builds multi versioned docs every time the default branch (e.g. `master`)  receives an update. If the build completes successfully, the workflow publishes the HTML version to GitHub Pages.                                      |
| `docs-pr.yaml`               | Builds the docs when the default branch receives a new pull request or when the pull request receives new commits. The purpose of this workflow is to make sure pull requests do not break the default branch after being merged. |
| `docs-links.yaml` (optional) | Looks for broken links once a week. If there are broken links, it creates an issue in the same repository with the list of affected links.                                                                                        |

## Installation

To install the workflows:

1. Copy the workflows named `docs-*.yaml` from [.github/workflows](https://github.com/scylladb/sphinx-scylladb-theme/blob/master/.github/workflows) to your project. The project’s directory structure should look like the following:
   > ```console
   > 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:
   > ```default
   > 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.
   > ![image](deployment/images/pages-configuration.png)
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](#available-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

#### NOTE
Setting up a custom domain requieres access to scylladb.com DNS configuration. Contact us in Slack `#scylla-docs` channel to set this configuration for you.

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.

> ![image](deployment/images/pages-custom-domain.png)
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](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages#verifying-a-domain-for-your-organization-site).
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 <i class="inline-icon icon-cancel" aria-hidden="true"></i> that you will see next to the commit message, and click on **Details**.
   > ![image](deployment/images/build-error.png)
2. Search for “warning” and “error” in the box you will find at the top right of the screen.
   > ![image](deployment/images/build-log.png)

You should see the error messages highlighted.

## Re-running a workflow

Re-running workflows is useful when:

- The theme received an update. By re-running the last build manually, the documentation project will receive the latest version. Otherwise, the theme will be automatically updated when the default branch gets an update.
- A previous version (branch or a tag) received a patch. Otherwise, the changes will not be reflected in production until the master branch gets an update.

To re-run a workflow see, [Re-running a workflow](https://docs.github.com/en/actions/managing-workflow-runs/re-running-a-workflow).

## Disabling GitHub Pages

To disable the docs deployment temporarily:

1. Delete the [workflows](#available-workflows) from `.github/workflows`.
2. Disable GitHub Pages from the repository settings. For more information, see  [Unpublishing a GitHub Pages Site](https://help.github.com/en/github/working-with-github-pages/unpublishing-a-github-pages-site#unpublishing-a-project-site).