• Docs
  • Ecosystem
  • Tutorial
  • Blog
  • GitHub
  • @QwikDev
  • Discord

Self-Hosting Qwik Applications

This guide provides comprehensive instructions for self-hosting your Qwik application on your own infrastructure, whether it's a VPS, bare metal server, or container platform.

Prerequisites

  • Node.js >= 16.8.0 (18.x LTS or later recommended)
  • A web server like Nginx, Apache, or similar for production deployments
  • (Optional) Docker for containerized deployments
  • (Optional) PM2 or similar for process management

Build Options

Qwik provides several adapters suited for self-hosting scenarios. Choose the one that best fits your infrastructure:

Fastify (Node.js)

Fastify offers better performance than Express and is another good option for self-hosting:

npx qwik add fastify

Static Site

For simple applications without dynamic server functionality:

npx qwik add static

When using the static adapter, make sure to update your adapters/static/vite.config.ts file with your actual domain:

staticAdapter({
  origin: 'https://your-actual-domain.com',
})

Building for Production

After adding the appropriate adapter, build your application. This will create a dist/ directory with all the necessary files for deployment:

pnpm run build

The build process will generate:

  • dist/ directory containing:

    • Vite-generated files:
      • dist/build/ – JavaScript and CSS bundles (code-split and optimized)
      • dist/assets/ – Fonts, images, and static assets processed by Vite
    • Non-Vite files (copied as-is):
      • Everything from the public/ folder (e.g., favicon, robots.txt, etc.)
    • Static site generation output (if SSG is used):
      • Pre-rendered .html pages
      • Route-specific q-data.json files
    • Manifest files:
      • manifest.json – For PWA support
      • q-manifest.json – Used during development, can be omitted from production

  • server/ directory:

    • Contains server entrypoints like entry.fastify.js or entry.express.js depending on the adapter used.

Deployment Methods

Method 1: Node.js Server Deployment

For Express or Fastify adapters, the build process generates a server entry file at server/entry.express.js or server/entry.fastify.js.

  1. Transfer these files to your production server:

    • dist/ (client assets)
    • server/ (server code)
    • package.json (for dependencies)

  2. Install production dependencies on the server:

pnpm install --prod
  1. Set the required environment variables:
# Important: This is required for CSRF protection
export ORIGIN=https://your-domain.com
 
# Set production mode
export NODE_ENV=production
 
# Optional: Define a custom port (default is 3000)
export PORT=3000
  1. Run the server:
# For Express
node server/entry.express.js
 
# For Fastify
node server/entry.fastify.js
  1. For production use, use a process manager like PM2:
npm install -g pm2
 
# For Express
pm2 start server/entry.express.js --name qwik-app
 
# For Fastify
pm2 start server/entry.fastify.js --name qwik-app

Using systemd

Create a systemd service file:

[Unit]
Description=Qwik Application
After=network.target
 
[Service]
Type=simple
User=qwikuser
WorkingDirectory=/path/to/your/app
ExecStart=/usr/bin/node server/entry.express.js
Restart=always
Environment=NODE_ENV=production
 
[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable qwik-app
sudo systemctl start qwik-app

Method 2: Docker Deployment

Using Docker is recommended for containerized deployments. Create a Dockerfile in your project root:

ARG NODE_VERSION=18.18.2

################################################################################
# Use node image for base image for all stages.
FROM node:${NODE_VERSION}-alpine as base

# Set working directory for all build stages.
WORKDIR /usr/src/app

################################################################################
# Create a stage for installing production dependencies.
FROM base as deps

# Download dependencies as a separate step to take advantage of Docker's caching.
# Leverage a cache mount to /root/.yarn to speed up subsequent builds.
RUN --mount=type=bind,source=package.json,target=package.json \
    --mount=type=bind,source=yarn.lock,target=yarn.lock \
    --mount=type=cache,target=/root/.yarn \
    yarn install --frozen-lockfile

################################################################################
# Create a stage for building the application.
FROM deps as build

# Copy the rest of the source files into the image.
COPY . .

# Run the build script.
RUN yarn run build

################################################################################
# Create a new stage to run the application with minimal runtime dependencies
FROM base as final

# Use production node environment by default.
ENV NODE_ENV production

# IMPORTANT: Set your actual domain for CSRF protection
ENV ORIGIN https://your-domain.com

# Run the application as a non-root user.
USER node

# Copy package.json so that package manager commands can be used.
COPY package.json .

# Copy the production dependencies from the deps stage and also
# the built application from the build stage into the image.
COPY --from=deps /usr/src/app/node_modules ./node_modules
COPY --from=build /usr/src/app/dist ./dist
COPY --from=build /usr/src/app/server ./server

# Expose the port that the application listens on.
EXPOSE 3000

# Run the application.
CMD yarn serve

Build and run your Docker container:

# Build the image
docker build -t qwik-app .
 
# Run the container
docker run -p 3000:3000 -e ORIGIN=https://your-domain.com qwik-app

Method 3: Static Site Deployment

If using the static adapter, copy the contents of the dist directory to your web server's document root:

# Example using rsync
rsync -avz dist/ user@your-server:/path/to/webroot/

Web Server Configuration

Web Server Configurations

1. Nginx for Node.js Applications

For Node.js deployments using Express or Fastify, use this Nginx configuration as a reverse proxy:

# HTTP to HTTPS redirect
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}
 
# Main server block
server {
    listen 443 ssl http2;
    server_name your-domain.com;
 
    # SSL configuration
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:10m;
 
    # Proxy to Node.js server
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
 
    # Static assets handling (build and assets directories)
    location ~ ^/(build|assets)/ {
        root /path/to/your/app/dist;
        expires 1y;
        add_header Cache-Control "public, max-age=31536000, immutable";
        access_log off;
    }
    
    # Security headers
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
}

2. Nginx for Static Sites

For static site deployments, use this Nginx configuration:

# HTTP to HTTPS redirect
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}
 
# Main server block
server {
    listen 443 ssl http2;
    server_name your-domain.com;
 
    # SSL configuration
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    
    # Document root
    root /path/to/your/app/dist;
    index index.html;
    
    # Security headers
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    
    # Main location block
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # Cache settings for static assets (build and assets directories)
    location ~ ^/(build|assets)/ {
        expires 1y;
        add_header Cache-Control "public, max-age=31536000, immutable";
        access_log off;
        try_files $uri =404;
        gzip_static on;
        brotli_static on;
    }
    
    # Route loader data caching
    location ~ /[^/]+/q-data\.json$ {
        expires 30s;
        add_header Cache-Control "public, must-revalidate";
        try_files $uri =404;
    }
    
    # Security: Deny access to hidden files
    location ~ /\. {
        deny all;
        access_log off;
        log_not_found off;
    }
    
    # Security: Deny access to .git directory
    location ^~ /.git/ {
        deny all;
        access_log off;
        log_not_found off;
    }
}

3. Apache Configuration

For Apache with mod_proxy enabled, use this configuration:

# HTTP to HTTPS redirect
<VirtualHost *:80>
    ServerName your-domain.com
    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
</VirtualHost>
 
# Main server block
<VirtualHost *:443>
    ServerName your-domain.com
    
    # SSL Configuration
    SSLEngine on
    SSLCertificateFile /path/to/cert.pem
    SSLCertificateKeyFile /path/to/key.pem
    
    # Proxy to Node.js server
    ProxyPreserveHost On
    ProxyPass / http://localhost:3000/
    ProxyPassReverse / http://localhost:3000/
    
    # Serve static assets directly (build and assets directories)
    <Directory /path/to/your/app/dist/build>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
        
        <IfModule mod_expires.c>
            ExpiresActive On
            ExpiresDefault "access plus 1 year"
            Header append Cache-Control "public, immutable"
        </IfModule>
    </Directory>
    
    # Alias for both build and assets directories
    AliasMatch ^/(build|assets)/(.*)$ /path/to/your/app/dist/$1/$2
    
    # Security headers
    Header always set X-Content-Type-Options "nosniff"
    Header always set X-Frame-Options "SAMEORIGIN"
    Header always set X-XSS-Protection "1; mode=block"
    
    # SPA fallback
    <IfModule mod_rewrite.c>
        RewriteEngine On
        RewriteBase /
        RewriteRule ^index\.html$ - [L]
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteRule . /index.html [L]
    </IfModule>
</VirtualHost>

Security Best Practices

CSRF Protection

Qwik City applications are protected against CSRF (Cross-Site Request Forgery) attacks by default for all state-mutating HTTP methods (POST, PATCH, DELETE). This protection is crucial for preventing unauthorized actions on behalf of authenticated users.

How It Works

  1. Default Protection: Enabled by default for all non-idempotent requests
  2. Origin Checking: Validates the Origin and Referer headers against the ORIGIN environment variable
  3. Configuration: Controlled via the checkOrigin option in createQwikCity

Configuration Options

// src/entry.express.tsx or src/entry.fastify.tsx
const { router, notFound } = createQwikCity({
  render,
  qwikCityPlan,
  manifest,
  // CSRF protection is enabled by default when ORIGIN is set
  checkOrigin: true
});
2. SSL Offload Proxy Setup

When behind a reverse proxy (Nginx, CloudFront, etc.), use 'lax-proto' to handle X-Forwarded-Proto headers:

const { router, notFound } = createQwikCity({
  render,
  qwikCityPlan,
  manifest,
  checkOrigin: 'lax-proto' // Required for proper proxy support
});
const { router, notFound } = createQwikCity({
  render,
  qwikCityPlan,
  manifest,
  checkOrigin: false // Disables CSRF protection (not recommended for production)
});

Essential Security Headers

Configure these security headers in your web server:

# Nginx example
add_header X-Content-Type-Options    "nosniff" always;
add_header X-Frame-Options          "SAMEORIGIN" always;
add_header X-XSS-Protection         "1; mode=block" always;
add_header Referrer-Policy          "strict-origin-when-cross-origin" always;
add_header Content-Security-Policy  "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data:;" always;

Additional Security Measures

  1. User Privileges

    • Run Node.js as a non-root user
    • Use process managers like PM2 with --user flag

  2. Network Security

    • Configure firewalls to expose only necessary ports (typically 80, 443)
    • Use fail2ban to protect against brute force attacks
    • Implement rate limiting for API endpoints

  3. Dependencies

    • Regularly update all dependencies
    • Use npm audit or yarn audit to identify vulnerabilities
    • Consider using Dependabot or similar tools

  4. HTTPS

    • Enforce HTTPS with HSTS header
    • Use modern TLS configurations (TLS 1.2/1.3)
    • Implement certificate auto-renewal (e.g., Certbot for Let's Encrypt)

  5. Application Hardening

    • Set appropriate file permissions
    • Disable directory listing
    • Protect sensitive files (e.g., .env, .git)
    • Implement proper CORS policies

  6. Monitoring & Logging

    • Monitor for suspicious activities
    • Implement centralized logging
    • Set up alerts for security events

Monitoring and Logging

Application Monitoring

1. Process Management with PM2

# Install PM2 globally
npm install -g pm2
 
# Start application
pm2 start dist/server/entry.express.js --name qwik-app
 
# Monitor application
pm2 monit
 
# View logs
pm2 logs qwik-app
 
# Set up PM2 to start on system boot
pm2 startup
pm2 save
 
# Set up PM2 dashboard (optional)
npm install -g pm2-web
pm2-web --config pm2-webrc.json

2. Web Server Logs

Nginx

# Access logs
/var/log/nginx/access.log
/var/log/nginx/error.log
 
# Enable JSON logging format in nginx.conf
log_format json_combined escape=json
  '{"timestamp":"$time_iso8601",'
  '"remote_addr":"$remote_addr",'
  '"remote_user":"$remote_user",'
  '"request":"$request",'
  '"status":"$status",'
  '"body_bytes_sent":"$body_bytes_sent",'
  '"http_referer":"$http_referer",'
  '"http_user_agent":"$http_user_agent"}';

Performance Monitoring

1. System-Level Monitoring

# Basic system monitoring
top
htop
nmon
 
# Network monitoring
iftop
iotop
 
# Disk I/O
iostat -x 1

2. Application Performance Monitoring (APM)

Using Prometheus + Grafana

  1. Set up Prometheus to collect metrics
  2. Configure Grafana for visualization
  3. Monitor key metrics:
    • Request rates
    • Error rates
    • Response times
    • Resource utilization

Alternative APM Solutions

Performance Optimization

Network Optimization

  1. HTTP/2 and HTTP/3

    • Enable HTTP/2 in Nginx/Apache
    • Consider HTTP/3 for modern browsers
    • Configure proper keep-alive settings

  2. CDN Integration

    • Use Cloudflare, CloudFront, or similar
    • Configure edge caching rules
    • Enable automatic image optimization

  3. Compression

    • Enable Brotli compression
    • Pre-compress static assets
    • Configure proper cache headers

Asset Optimization

  1. Caching Strategy

    # Immutable assets (hashed filenames)
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, max-age=31536000, immutable";
    access_log off;
}

  2. Lazy Loading

    • Use Qwik's built-in lazy loading
    • Split large components
    • Implement route-based code splitting

  3. Image Optimization

    • Use modern formats (WebP/AVIF)
    • Implement responsive images
    • Lazy load below-the-fold images

Server-Side Optimization

  1. Node.js Tuning

    • Set appropriate NODE_ENV=production
    • Tune V8 garbage collection
    • Use worker threads for CPU-intensive tasks

  2. Database Optimization

    • Implement connection pooling
    • Add appropriate indexes
    • Use query optimization techniques

  3. Caching Layer

    • Implement Redis/Memcached
    • Cache API responses
    • Use stale-while-revalidate patterns

Asset Compression

Enable efficient compression for static assets:

  1. Pre-compress static files during build:
# Install compression tools
npm install -g brotli-cli gzip-cli
 
# Compress build assets in parallel with maximum compression
find dist/build dist/assets -type f -regex '.*\.\(js\|css\|html\|json\)$' -print0 | xargs -0 gzip -9 -k &
find dist/build dist/assets -type f -regex '.*\.\(js\|css\|html\|json\)$' -print0 | xargs -0 brotli -15 -k &
wait
  1. Configure Nginx to serve pre-compressed files:
location ~ ^/(build|assets)/ {
    root /path/to/your/app/dist;
    expires 1y;
    add_header Cache-Control "public, max-age=31536000, immutable, no-transform" always;
    access_log off;
    # Enable pre-compressed file serving
    gzip_static on;
    brotli_static on;
    try_files $uri =404;
}

Scaling Considerations

For high-traffic applications:

  1. Set up load balancing with multiple Node.js instances
  2. Use container orchestration (Kubernetes, Docker Swarm)
  3. Consider a microservices architecture for larger applications
  4. Implement Redis or similar for session management across instances
  5. Use a serverless approach for predictable scaling

Troubleshooting Common Issues

  1. 404 Not Found:

    • Check your Nginx/Apache configuration paths
    • Verify that URL rewriting is properly configured
    • Check file permissions: Ensure the web server user has read access to all files and execute permission on all parent directories 
      # Check permissions for a specific file
sudo -u nginx ls -ld /path/to/static/file
 
# Check directory permissions (go up the path to find where access is denied)
sudo -u nginx ls -ld /path/to/static/
sudo -u nginx ls -ld /path/to/
sudo -u nginx ls -ld /path/
 
# NixOS-specific: Web server users typically don't have access to /home by default
# You may need to adjust the permissions or move the files to /var/www or similar

  2. 503 Service Unavailable:

    • Verify the Node process is running (pm2 list or ps aux | grep node)
    • Check server logs for memory issues or crashes

  3. CSRF Errors:

    • Ensure the ORIGIN environment variable is correctly set
    • Check that form submissions include the correct CSRF token

  4. Performance Issues:

    • Enable compression in your web server
    • Check for memory leaks using Node.js profiling
    • Verify that static assets are served with proper cache headers

  5. Missing Assets:

    • Ensure your build process is complete
    • Check that the /build/ and /assets/ directories are correctly exposed

Contributors

Thanks to all the contributors who have helped make this documentation better!

  • iitzIrFan