Hosting and deploys

By default, Stainless manages the build and deployment pipeline for fully hosted Stainless Docs sites.

You can also move the underlying Astro project to your own GitHub organization, build it in your own CI system, and deploy the generated static site to the hosting provider of your choice. This guide describes how to migrate a Stainless-hosted docs site to your own infrastructure.

A self-hosted Stainless Docs deployment has three parts:

1. Source control: the docs site is backed by a git repository that lives in your GitHub organization or on the git provider of your choice.
2. Build pipeline: your CI system installs dependencies and runs the Astro build, generating fully static assets suitable for deployment.
3. Hosting: the generated static site is deployed to your chosen hosting provider or CDN service.

After migration, your organization is fully responsible for the repository, CI configuration, deployment target, domain configuration, and other operational concerns.

Prerequisites

Ensure that you have the following prerequisites in order to complete the migration process:

• Access to the existing Stainless Docs GitHub repository.
• Permission to create repositories in your GitHub organization.
• A deployment target, such as Cloudflare Pages, Vercel, Netlify, GitHub Pages, or another static hosting provider.
• Access to configure DNS for your docs domain.
• Any environment variables required by your docs site.
• Your docs site is up to date (@stainless-api/docs version 1.0.0-beta.143 or newer)
• You are rendering API reference from a local OpenAPI spec and Stainless config file.

Fork your Stainless Docs repository

To assume control of your Stainless Docs site, you must first fork the underlying git repository to your own organization on GitHub.

Stainless stores the underlying repositories for Stainless Docs sites in the stainless-sdks organization on GitHub. To find your docs repository and reach it on the GitHub website:

1. Navigate to the Overview tab of your project in Stainless Studio
2. Find the API Documentation block in the list of your project’s SDK codegen targets
3. Click the repository link that appears in the API Documentation block

To fork the repository, navigate to the repository page on GitHub and click the Fork button. Follow the on-screen instructions to complete the fork process.

Choose a hosting provider

Stainless Docs sites can be deployed to any hosting provider that supports static sites.

We strongly recommend hosting your site with Cloudflare Pages, which offers a generous free tier and a built-in CDN that serves your site from edge locations around the world.

The rest of this guide assumes you’re using Cloudflare Pages, but the process is similar for other providers.

Deploy to Cloudflare Pages

After you connect it to your Stainless Docs repository, Cloudflare Pages automatically rebuilds and publishes the site whenever it detects changes in the git repository. Cloudflare natively supports building Astro sites, so minimal configuration is required.

Use the following steps to connect Cloudflare Pages to your git repository:

1. Log into the Cloudflare dashboard and navigate to Workers & Pages in the Compute section of the sidebar
2. Click the Create Application button in the top right-hand corner
3. Click the Get Started link next to Looking to deploy Pages?
4. Click the Get Started button next to Import an existing Git repository
5. Click the Connect Github button in the Deploy a site from your account dialog
6. Click the Add Account button on the Github tab of the Deploy a site from your account panel
7. In the Github popup window, select the organization that owns your Stainless Docs repository
8. Click the Only select repositories option and select your Stainless Docs repository
9. Click the Authorize button to grant Cloudflare read-only access to the specified repository
10. In the Deploy a site from your account dialog, select your Stainless Docs repository and click the Begin Setup button
11. Set the Framework preset selector to Astro
12. Click the Save and Deploy button to complete the process

When you complete the setup process, Cloudflare Pages automatically builds and deploys your site. Cloudflare assigns your site a *.pages.dev subdomain which it uses to serve the content to the public internet. When you visit that subdomain, you should see a fully rendered version of your website.

Update DNS configuration to use your own domain

To serve your Stainless Docs site from your own domain, you can use a DNS CNAME record and point it to the Cloudflare Pages site.

1. In the Cloudflare dashboard, navigate to Workers & Pages in the Compute section of the sidebar
2. Click through to the project associated with your Stainless Docs site
3. Navigate to the Custom Domains tab click the Set up a custom domain button
4. Enter the domain or subdomain that you would like to use for your site
5. Click the Begin CNAME setup button to begin configuring your DNS provider
6. In your DNS provider’s configuration dashboard, create a CNAME record using the fields provided by Cloudflare
7. After you have successfully created the CNAME record at your DNS provider, lick the Check DNS records button in the Cloudflare dashboard to initiate the verification check

It may take some time for your newly-created CNAME record to propagate. The domain mapping activates automatically when Cloudflare is able to successfully verify that the CNAME record exists.

Configure search with Algolia

Stainless Docs sites automatically use Astro Starlight’s built-in Pagefind indexer to support searching guides and other long-form content. Stainless Docs also has optional support for searching the API reference, powered by Algolia. You can enable this feature in a self-hosted Stainless Docs site by providing Algolia API keys via environment variables.

Obtain Algolia API keys

Use the following steps to create a new application in the Algolia dashboard and obtain API keys:

1. In the Algolia dashboard, open the application menu in the top navigation bar
2. Click the Create Application button in the Algolia application selector
3. Input your Algolia application name and select an Algolia plan
4. Click the Next button to review your selection
5. Click the Create Application button to complete the process
6. On the Get Started page, click the Skip for now button in the top left-hand corner to skip the data import process
7. On the Welcome screen, copy your Application ID, Search API Key, and Write API Key

Add Algolia keys to Cloudflare Pages project

To enable Algolia search and indexing in your Stainless Docs site, configure the following environment variables:

Variable name	Variable value
PUBLIC_ALGOLIA_APP_ID	The Application ID from your Algolia application
PUBLIC_ALGOLIA_SEARCH_KEY	The public Search API key provided by Algolia
PRIVATE_ALGOLIA_WRITE_KEY	The private Write API Key key provided by Algolia
PUBLIC_ALGOLIA_INDEX	The name of the Algolia index in which to store API reference information, e.g. api-docs-index

Use the following steps to add each environment variable in your Cloudflare Pages project:

1. In the Cloudflare dashboard, navigate to Workers & Pages in the Compute section of the sidebar
2. Click through to the project associated with your Stainless Docs site
3. Navigate to Variables and Secrets in your project’s Settings tab in the dashboard
4. Click the Add button in the Variables and Secrets section to add an environment variable
5. Input the environment variable’s name and value in the dialog and click the Save button

After configuring the environment variables, your site will automatically index the API reference content and enable the search functionality the next time it builds.

Tips for other hosting providers

If you are using a hosting provider other than Cloudflare Pages, you may need to configure additional settings to ensure a quality user experience for your site.

Configuring cache headers

Because Stainless Docs sites are multi-page static sites, setting the proper cache headers is critical to ensure that your site is performant.

Assets in the _astro directory are versioned, and therefore can be cached indefinitely. We recommend the following cache headers for these assets:

Cache-Control: public, max-age=604800, immutable

Other files in the dist directory, including HTML files, should be cached for a shorter period of time, depending on how often you expect them to change.