Skip to main content

​
Deployment Guide

RADS-R Self-Host is a static web application that can be deployed to any hosting provider that serves HTML, CSS, and JavaScript files. No backend or database required.

​
Deployment Overview

The application is built using Vite, which generates a production-optimized build in the dist/ directory. This folder contains everything needed to run the application.
All hosting options serve the same static files. Choose based on your familiarity, existing infrastructure, or specific requirements.

​
Build for Production

Before deploying, create a production build: 
npm run build
This command:
  1. Compiles TypeScript to JavaScript
  2. Bundles all dependencies
  3. Optimizes assets (minification, tree-shaking)
  4. Outputs to the dist/ directory
The dist/ folder structure: 
dist/
├── index.html          # Entry point
├── assets/
│   ├── index-[hash].js # Bundled JavaScript
│   └── index-[hash].css # Bundled CSS
└── vite.svg           # Static assets
The [hash] in filenames enables cache busting, ensuring users get the latest version after updates.

​
Static Hosting Providers

Deploy to any static hosting provider with minimal configuration.

​
Netlify

Deploy to Netlify with automatic builds from Git:
1

Connect repository

  1. Sign in to Netlify
  2. Click “Add new site” → “Import an existing project”
  3. Connect your Git provider and select the repository
2

Configure build settings

Set the following build settings:
  • Build command: npm run build
  • Publish directory: dist
  • Node version: 18 or higher (set in Environment variables)
3

Deploy

Click “Deploy site”. Netlify will build and deploy automatically.Future pushes to your main branch will trigger automatic deployments.
Optional: Create a netlify.toml for configuration:
netlify.toml
[build]
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

​
Vercel

Deploy to Vercel with zero configuration:
1

Import project

  1. Sign in to Vercel
  2. Click “Add New” → “Project”
  3. Import your Git repository
2

Configure (auto-detected)

Vercel automatically detects Vite projects and sets:
  • Build command: npm run build
  • Output directory: dist
  • Install command: npm install
3

Deploy

Click “Deploy”. Vercel builds and deploys with automatic previews for pull requests.

​
Cloudflare Pages

Deploy to Cloudflare Pages with global CDN:
1

Create project

  1. Sign in to Cloudflare
  2. Navigate to Pages → “Create a project”
  3. Connect your Git provider
2

Configure build

Set build configuration:
  • Framework preset: Vite
  • Build command: npm run build
  • Build output directory: dist
3

Deploy

Click “Save and Deploy”. Future commits trigger automatic deployments.

​
GitHub Pages

Deploy to GitHub Pages for free hosting:
1

Update vite.config.ts

Set the base path for GitHub Pages:
vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  base: '/raads-r-self-host/', // Replace with your repo name
  test: {
    globals: true,
  },
})
2

Build and deploy

Build and push to gh-pages branch:
npm run build
git subtree push --prefix dist origin gh-pages
3

Enable GitHub Pages

  1. Go to repository Settings → Pages
  2. Source: Deploy from a branch
  3. Branch: gh-pages → / (root)
  4. Save
Alternative: Use GitHub Actions for automated deployments:
.github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18
          
      - name: Install dependencies
        run: npm install
        
      - name: Build
        run: npm run build
        
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

​
AWS S3 + CloudFront

Deploy to AWS with S3 for storage and CloudFront for CDN:
1

Create S3 bucket

aws s3 mb s3://raads-r-app
aws s3 website s3://raads-r-app --index-document index.html
2

Upload build

npm run build
aws s3 sync dist/ s3://raads-r-app --delete
3

Configure CloudFront (optional)

Create a CloudFront distribution pointing to the S3 bucket for global CDN and HTTPS.

​
Docker Deployment

Run the application in a Docker container with nginx:
1

Create Dockerfile

Create a multi-stage Dockerfile:
Dockerfile
# Build stage
FROM node:18-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .
RUN npm run build

# Production stage
FROM nginx:alpine

COPY --from=builder /app/dist /usr/share/nginx/html

# Optional: Custom nginx config
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]
2

Create nginx config (optional)

nginx.conf
server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
3

Build and run

# Build the image
docker build -t raads-r-app .

# Run the container
docker run -d -p 8080:80 raads-r-app
Access the application at http://localhost:8080
Docker Compose (optional):
docker-compose.yml
version: '3.8'

services:
  raads-r:
    build: .
    ports:
      - "8080:80"
    restart: unless-stopped
Run with: docker-compose up -d

​
Self-Hosted Options

Deploy to your own infrastructure:

​
Apache

  1. Build the application: npm run build
  2. Copy dist/ contents to Apache document root: /var/www/html/
  3. Configure .htaccess for SPA routing:
.htaccess
<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

​
Nginx

  1. Build the application: npm run build
  2. Copy dist/ contents to nginx html directory: /usr/share/nginx/html/
  3. Configure nginx for SPA routing:
/etc/nginx/sites-available/raads-r
server {
    listen 80;
    server_name your-domain.com;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|svg|ico)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
  1. Enable site and reload nginx:
sudo ln -s /etc/nginx/sites-available/raads-r /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

​
Environment Considerations

​
HTTPS Requirement

Modern browsers require HTTPS for service workers and certain web APIs. Always deploy with HTTPS in production.
Most hosting providers (Netlify, Vercel, Cloudflare Pages) provide automatic HTTPS. For self-hosted:
  • Use Let’s Encrypt for free SSL certificates
  • Configure nginx/Apache with SSL
  • Use Cloudflare for SSL termination

​
Base Path Configuration

If deploying to a subdirectory (e.g., example.com/raads-r/), update vite.config.ts:
vite.config.ts
export default defineConfig({
  base: '/raads-r/', // Set to your subdirectory path
  // ... other config
})

​
Build Optimization

The production build is automatically optimized by Vite:
  • Minification: JavaScript and CSS are minified
  • Tree-shaking: Unused code is removed
  • Code splitting: Automatic chunking for optimal loading
  • Asset hashing: Cache busting for static assets

​
Verification

After deployment, verify the application works correctly:
1

Load the application

Visit your deployment URL and ensure the landing page loads.
2

Test functionality

  • Start the questionnaire
  • Answer a few questions
  • Navigate forward and backward
  • Test dark/light mode toggle
3

Check console

Open browser DevTools and check for errors in the console.
4

Test offline mode

Disconnect from the internet and verify the app still functions (after initial load).

​
Continuous Deployment

Automate deployments with Git-based workflows:
  1. Push to main branch triggers automatic deployment
  2. Pull request previews for testing before merge (Netlify, Vercel)
  3. Rollback capability to previous versions if issues arise
  4. Build logs for debugging deployment failures
Most providers offer preview deployments for pull requests, allowing you to test changes before merging to production.

​
Performance Considerations

  • CDN: Use providers with global CDN (Netlify, Vercel, Cloudflare)
  • Caching: Static assets are cached with far-future expires headers
  • Compression: Enable gzip/brotli compression on your server
  • Lazy loading: Vite automatically code-splits for optimal loading

​
Next Steps

Customization

Customize the questionnaire and UI to fit your needs.

User Guide

Learn how to use the questionnaire and interpret results.

Build docs developers (and LLMs) love

Get started for freeTalk to us