Hosting and deploys

Stainless Docs sites can be hosted on Stainless or on any hosting provider that supports static sites.

Choosing a provider

We recommend you host your Stainless Docs site on Stainless, which offers a few advantages:

• Automatic builds and deploys when your APIs or SDKs change
• AI search indexing powered by Algolia
• Optimized performance for SEO and GEO
• Pre-configured asset caching behind a global CDN
• A generous free tier, including free custom domains with automatic SSL

Host with Stainless

When you setup your site through the Stainless dashboard, your site is automatically deployed on Stainless infrastructure. When you’re ready to go to production, add a custom domain.

Host elsewhere

If Stainless hosting doesn’t meet your needs, or if you prefer to host your site yourself, Stainless Docs sites can be hosted anywhere that supports static sites.

First, generate a static build of your site:

pnpm build

When you run this build command, your static site will be generated in the dist directory. If you have a deployment pipeline, you should add this build command to it so your site is regenerated every time you deploy.

You can preview the resulting static site locally by running the following command:

pnpm preview

The static site inside your dist directory can be hosted anywhere that supports static site hosting, such as GitHub Pages, Vercel, Cloudflare Pages, Netlify, and many other web hosts.

Site search

By default, your static site will use Pagefind for basic site search.

If you have an Algolia account, you can enable advanced search functionality by passing the following environment variables into the build command:

Environment variable	Description
PUBLIC_ALGOLIA_APP_ID	Your Algolia app ID
PUBLIC_ALGOLIA_INDEX	The name of the index to use for search indexing
PUBLIC_ALGOLIA_SEARCH_KEY	Your Algolia search API key
PRIVATE_ALGOLIA_WRITE_KEY	Your Algolia API key

Configuring cache headers

When you host with Stainless, we automatically set the correct cache headers for each file. When you host your site elsewhere, you need to set these yourself 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.