Quick Start - Deploy Your Site

s:CMS can be deployed to any static hosting platform. Choose your preferred option below.

GitHub Pages

Option 1: GitHub Actions (Recommended)

1. Configure your site URL in usr/user.config.mjs:

   1
   export const siteMetadata = {
   2
     siteUrl: 'https://username.github.io/repo-name',
   3
   }

2. Create GitHub Actions workflow: Create .github/workflows/deploy.yml:

   1
   name: Deploy to GitHub Pages
   2
   
   3
   on:
   4
     # Runs on pushes targeting the default branch
   5
     push:
   6
       branches: ["main"]
   7
   
   8
     # Allows you to run this workflow manually from the Actions tab
   9
     workflow_dispatch:
   10
   
   11
   # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
   12
   permissions:
   13
     contents: read
   14
     pages: write
   15
     id-token: write
   16
   
   17
   # Allow only one concurrent deployment
   18
   concurrency:
   19
     group: "pages"
   20
     cancel-in-progress: false
   21
   
   22
   jobs:
   23
     build:
   24
       runs-on: ubuntu-latest
   25
       steps:
   26
         - name: Checkout
   27
           uses: actions/checkout@v4
   28
   
   29
         - name: Setup Node
   30
           uses: actions/setup-node@v4
   31
           with:
   32
             node-version: "20"
   33
             cache: npm
   34
   
   35
         - name: Install dependencies
   36
           run: npm ci
   37
   
   38
         - name: Build with Astro
   39
           run: npm run build
   40
   
   41
         - name: Upload artifact
   42
           uses: actions/upload-pages-artifact@v3
   43
           with:
   44
             path: ./dist
   45
   
   46
     deploy:
   47
       environment:
   48
         name: github-pages
   49
         url: ${{ steps.deployment.outputs.page_url }}
   50
       runs-on: ubuntu-latest
   51
       needs: build
   52
       steps:
   53
         - name: Deploy to GitHub Pages
   54
           id: deployment
   55
           uses: actions/deploy-pages@v4

3. Enable GitHub Pages in repo settings:

   • Settings → Pages → Source: GitHub Actions

4. Push to GitHub - automatic deployment on every push

Option 2: Manual Build & Deploy

1
npm run build
2
# Upload dist/ folder to GitHub Pages via gh-pages branch
3
npx gh-pages -d dist

Netlify

1. Connect your GitHub repository
2. Build settings:
   • Build command: npm run build
   • Publish directory: dist
3. Deploy

With Environment Variables:

1
[build]
2
  command = "npm run build"
3
  publish = "dist"
4

5
[build.environment]
6
  NODE_VERSION = "20"
7

8
# Optional: Set environment variables
9
# DIRECTUS_URL = "https://your-directus.com"
10
# DIRECTUS_TOKEN = "your-token"

Vercel

1. Import your GitHub repository
2. Framework Preset: Astro
3. Deploy

With Environment Variables:

1
{
2
  "buildCommand": "npm run build",
3
  "outputDirectory": "dist",
4
  "framework": "astro"
5
}

Add secrets in Vercel dashboard: Settings → Environment Variables

Cloudflare Pages

1. Connect your GitHub repository
2. Build settings:
   • Build command: npm run build
   • Build output directory: dist
3. Deploy

With Environment Variables: Add in Cloudflare dashboard: Settings → Environment variables

Traditional Hosting (FTP/SSH)

1
# Build locally
2
npm run build
3

4
# Upload dist/ folder to your server
5
# Via FTP, rsync, or your hosting panel

Managing Secrets & Environment Variables

If your site uses Directus, external APIs, or other services requiring credentials, never commit secrets to your repository.

Local Development

Create .env file (gitignored by default):

1
DIRECTUS_URL=https://your-directus-instance.com
2
DIRECTUS_TOKEN=your_secret_token
3
PUBLIC_SITE_URL=http://localhost:4321

Access in your code:

1
import.meta.env.DIRECTUS_URL
2
import.meta.env.DIRECTUS_TOKEN
3
import.meta.env.PUBLIC_SITE_URL // Available in client code

Deployment Platform Setup

GitHub Actions:

Add secrets to your repository:

1. Go to: Settings → Secrets and variables → Actions
2. Click “New repository secret”
3. Add your secrets (e.g., DIRECTUS_TOKEN)

Update your GitHub Actions workflow to use secrets:

1
jobs:
2
  build:
3
    runs-on: ubuntu-latest
4
    steps:
5
      # ... other steps ...
6

7
      - name: Build with Astro
8
        run: npm run build
9
        env:
10
          DIRECTUS_URL: ${{ secrets.DIRECTUS_URL }}
11
          DIRECTUS_TOKEN: ${{ secrets.DIRECTUS_TOKEN }}
12
          PUBLIC_SITE_URL: ${{ vars.PUBLIC_SITE_URL }}

Note: Use secrets for sensitive data, vars for non-sensitive configuration.

Platform-Specific Secrets

Netlify:

• Dashboard → Site settings → Environment variables
• Or via netlify.toml:

1
[context.production.environment]
2
  PUBLIC_SITE_URL = "https://yourdomain.com"

Vercel:

• Dashboard → Project Settings → Environment Variables
• Set for: Production, Preview, Development

Cloudflare Pages:

• Dashboard → Settings → Environment variables
• Separate settings for Production and Preview

Security Best Practices

1. ✅ Never commit .env files - Already in .gitignore
2. ✅ Use PUBLIC_ prefix for client-side variables only
3. ✅ Rotate secrets regularly - Especially after team changes
4. ✅ Use different secrets per environment - Production vs. Preview
5. ❌ Don’t log secrets - Be careful with console.log in production
6. ❌ Don’t expose server-side secrets - Keep them in .env, not in public code

Example: Directus Integration with Secrets

usr/content/config.ts:

1
import { defineCollection } from 'astro:content';
2
import { directusLoader } from '@core/integrations/directusLoader';
3

4
const articlesCollection = defineCollection({
5
  loader: directusLoader({
6
    url: import.meta.env.DIRECTUS_URL,
7
    token: import.meta.env.DIRECTUS_TOKEN,
8
    collection: 'articles',
9
  }),
10
});
11

12
export const collections = {
13
  articles: articlesCollection,
14
};

Required secrets:

• DIRECTUS_URL - Your Directus instance URL
• DIRECTUS_TOKEN - Static token with read permissions

Custom Build Scripts

Add to package.json:

1
{
2
  "scripts": {
3
    "build:prod": "astro check && astro build",
4
    "build:preview": "astro build --mode preview",
5
    "deploy": "npm run build && npx gh-pages -d dist"
6
  }
7
}

Continuous Deployment Options

Option 1: Direct Git Push

• GitHub Pages, Netlify, Vercel auto-deploy on git push

Option 2: GitHub Actions (Custom)

Create .github/workflows/deploy.yml with your platform-specific deployment

Option 3: Platform CLI

1
# Netlify
2
npm install -g netlify-cli
3
netlify deploy --prod
4

5
# Vercel
6
npm install -g vercel
7
vercel --prod

Troubleshooting Deployment

Build Fails

Check Node version:

1
- name: Setup Node
2
  uses: actions/setup-node@v4
3
  with:
4
    node-version: "20"  # Match your local version

Check dependencies:

1
rm -rf node_modules package-lock.json
2
npm install
3
npm run build

Site Shows 404

For GitHub Pages project sites, set base in astro.config.mjs:

1
export default {
2
  site: 'https://username.github.io',
3
  base: '/repo-name',
4
}

For custom domains, no base needed:

1
export default {
2
  site: 'https://yourdomain.com',
3
}

Environment Variables Not Working

• ✅ Restart dev server after adding .env
• ✅ Use PUBLIC_ prefix for client-side access
• ✅ Check variable names match exactly (case-sensitive)
• ✅ Verify secrets are set in deployment platform

Images Not Loading

Check image paths:

• Use /images/photo.jpg for files in usr/public/images/
• Use relative paths ./photo.jpg for images next to content
• Astro optimizes images automatically

Performance Optimization

Build Optimization

1
export default {
2
  build: {
3
    inlineStylesheets: 'auto',
4
  },
5
  image: {
6
    service: {
7
      entrypoint: 'astro/assets/services/sharp',
8
    },
9
  },
10
}

Caching Strategy

For GitHub Actions:

1
- name: Setup Node
2
  uses: actions/setup-node@v4
3
  with:
4
    node-version: "20"
5
    cache: npm  # Caches node_modules

For Netlify/Vercel:

• Built-in caching enabled automatically
• Clear cache in settings if needed

Keeping s:CMS Up-to-Date

s:CMS uses a core/usr architecture that keeps framework updates separate from your content.

First Time Setup

After creating your site from the template:

1
npm run setup-upstream

This configures the connection to receive s:CMS updates.

Updating to Latest Version

1
npm run update-core

This script will:

• Create a backup of your current code
• Fetch the latest s:CMS version
• Merge updates while protecting your usr/ folder
• Install new dependencies if needed

Your content and customizations in usr/ are never overwritten! 🛡️

What Gets Updated

Detailed Documentation

For complete update instructions, troubleshooting, and conflict resolution:

📖 Read the full Update Guide

Best Practices

1. Update regularly - Smaller updates are easier to merge
2. Test locally - Always run npm run dev after updating
3. Read changelogs - Review what’s changing in each release
4. Don’t edit core/ - Make all customizations in usr/

Need help? Check out docs/UPDATING.md for detailed instructions!