Guides
View as Markdown Open in ChatGPT Open in Claude

Self-Hosted Deployment

While Syntext provides managed hosting with global CDN and SSL, you can also deploy the generated static files to your own infrastructure.

Self-hosted deployment is available on Enterprise plans. Contact us to learn more.

Build for Self-Hosting

Generate the static site with the CLI. The build runs on the Syntext backend and the compiled files are downloaded to your machine:

stx build --output ./dist

This creates a dist/ folder containing:

dist/
├── index.html
├── getting-started.html        # one .html per page
├── guides/
│   └── *.html
├── api-reference/
│   └── *.html
├── ask.html                    # full-page AI chat route
├── 404.html
├── _assets/
│   └── search-index.json       # static search index
├── sitemap.xml
├── robots.txt
└── (your public/ assets)

Pages are flat .html files — configure your host to resolve extensionless URLs (see the Nginx example below).

Hosting Options

Static Site Hosting

Deploy to any static file host:

AWS S3 + CloudFront

# Sync to S3
aws s3 sync ./dist s3://your-docs-bucket --delete

# Invalidate CloudFront cache
aws cloudfront create-invalidation --distribution-id EXXX --paths "/*"

Cloudflare Pages

# Using Wrangler
wrangler pages deploy ./dist --project-name=your-docs

Nginx

server {
    listen 80;
    server_name docs.yourcompany.com;
    root /var/www/docs;
    
    location / {
        try_files $uri $uri/ $uri.html =404;
    }
}

Docker

Build a containerized version:

FROM nginx:alpine
COPY ./dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

docker build -t my-docs .
docker run -p 8080:80 my-docs

Self-Hosted Features

Every stx build includes a static search index:

  1. The build generates _assets/search-index.json automatically
  2. The client-side search library uses this index directly — no API calls needed

Client-side search works well for small-to-medium sites (< 500 pages). For larger sites, consider hosting your own Meilisearch instance.

AI Assistant

The AI assistant requires API access. For self-hosted AI:

  1. Deploy your own RAG service
  2. Configure the endpoint in syntext.json: 
    {
  "ai": {
    "apiUrl": "https://your-ai-service.internal/v1",
    "projectId": "your-project"
  }
}

Analytics

Self-hosted deployments don't include Syntext analytics by default. Options:

  • Plausible: Add script to syntext.json → scripts.head
  • PostHog: Add tracking snippet
  • Custom: Implement your own analytics endpoint
{
  "scripts": {
    "head": "<script src='https://plausible.io/js/script.js' data-domain='docs.yourcompany.com'></script>"
  }
}

Continuous Deployment

GitHub Actions (Self-Hosted)

name: Deploy Docs

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: oven-sh/setup-bun@v1
      
      - name: Install CLI
        run: bun install -g @syntext/cli
        
      - name: Build
        run: stx build --output ./dist
        
      - name: Deploy to S3
        run: aws s3 sync ./dist s3://${{ secrets.S3_BUCKET }} --delete
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

Limitations

Self-hosted deployments don't include:

Feature Self-Hosted Managed
Global CDN ❌ ✅
Automatic SSL ❌ ✅
Preview deployments ❌ ✅
Built-in analytics ❌ ✅
AI assistant (default) ❌ ✅
Zero-config search ❌ ✅

You can replicate these features with your own infrastructure, but it requires additional setup.

Was this page helpful?