Skip to content
Klutch.sh Docs

Deploying ChiefOnboarding

Introduction

ChiefOnboarding is a powerful open-source employee onboarding platform that helps organizations automate and streamline the entire onboarding process for new hires. Built with Django and modern web technologies, ChiefOnboarding enables HR teams and managers to create customized onboarding workflows, assign tasks, track progress, send automated notifications, and integrate seamlessly with popular tools like Slack, email, and calendar systems.

Deploying ChiefOnboarding on Klutch.sh provides a production-ready, scalable infrastructure for your employee onboarding automation with automated Docker deployments, persistent storage for employee data and documents, secure environment variable management, and enterprise-grade reliability. Whether you’re onboarding new employees at a startup, managing complex workflows at a growing company, or implementing multi-department onboarding processes, Klutch.sh simplifies the deployment process and ensures your ChiefOnboarding instance is always available.

This comprehensive guide walks you through deploying ChiefOnboarding on Klutch.sh using a Dockerfile, configuring PostgreSQL databases, setting up persistent volumes for data retention and media files, managing environment variables for security and integrations, and implementing production best practices for scalable HR automation and employee onboarding management.

Prerequisites

Before you begin deploying ChiefOnboarding on Klutch.sh, ensure you have:

  • A Klutch.sh account (sign up here)
  • A GitHub repository for your ChiefOnboarding deployment configuration
  • Basic understanding of Docker containers and environment variables
  • A PostgreSQL database instance (recommended for production)
  • (Optional) Slack workspace with API credentials for integration
  • (Optional) SMTP server credentials for email notifications
  • Access to the Klutch.sh dashboard

Understanding ChiefOnboarding Architecture

ChiefOnboarding consists of several key components:

  • Django Application: Python-based web framework handling business logic, API endpoints, and data management
  • Celery Workers: Background task processing for scheduled notifications, email delivery, and workflow automation
  • Redis: Required for Celery message queuing and caching
  • PostgreSQL Database: Stores employee data, onboarding workflows, tasks, and system configurations
  • Static Files & Media: User uploads, profile pictures, documents, and static assets
  • NGINX/Gunicorn: Web server and WSGI application server for handling HTTP requests

When deployed on Klutch.sh, ChiefOnboarding automatically detects your Dockerfile and builds a container image that includes all necessary components. The platform manages traffic routing, SSL certificates, and provides persistent storage options for your application data.

Project Structure

A minimal repository structure for deploying ChiefOnboarding on Klutch.sh:

chiefonboarding-deployment/
├── Dockerfile
├── docker-entrypoint.sh
├── .dockerignore
├── .gitignore
├── .env.example
└── README.md

This simple structure allows Klutch.sh to automatically detect and build your ChiefOnboarding container. The official ChiefOnboarding Docker image comes pre-configured with the application code.

Creating Your Dockerfile

Klutch.sh automatically detects a Dockerfile in the root directory of your repository. Create a Dockerfile that uses the official ChiefOnboarding image or builds from source:

FROM chiefonboarding/chiefonboarding:latest


# Expose the default ChiefOnboarding port
EXPOSE 8000


# The official image includes an entrypoint script
# that handles database migrations and service startup
CMD ["sh", "-c", "python manage.py migrate && python manage.py collectstatic --noinput && gunicorn -b 0.0.0.0:8000 chiefonboarding.wsgi:application"]

Option 2: Production Dockerfile with Health Checks

FROM chiefonboarding/chiefonboarding:latest


# Set working directory
WORKDIR /app


# Create directories for media and static files
RUN mkdir -p /app/media /app/staticfiles


# Expose the application port
EXPOSE 8000


# Add health check for monitoring
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:8000/health/ || exit 1


# Copy custom entrypoint if needed
COPY docker-entrypoint.sh /app/docker-entrypoint.sh
RUN chmod +x /app/docker-entrypoint.sh


# Start application with migrations and static files
ENTRYPOINT ["/app/docker-entrypoint.sh"]
CMD ["gunicorn", "-b", "0.0.0.0:8000", "--workers", "3", "--timeout", "120", "chiefonboarding.wsgi:application"]

Option 3: Custom Dockerfile Building from Source

FROM python:3.11-slim


# Install system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    postgresql-client \
    libpq-dev \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*


# Set working directory
WORKDIR /app


# Clone ChiefOnboarding repository
RUN git clone https://github.com/chiefonboarding/ChiefOnboarding.git /app


# Install Python dependencies
RUN pip install --no-cache-dir -r requirements.txt


# Create directories
RUN mkdir -p /app/media /app/staticfiles


# Expose port
EXPOSE 8000


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:8000/health/ || exit 1


# Copy entrypoint script
COPY docker-entrypoint.sh /app/docker-entrypoint.sh
RUN chmod +x /app/docker-entrypoint.sh


ENTRYPOINT ["/app/docker-entrypoint.sh"]
CMD ["gunicorn", "-b", "0.0.0.0:8000", "--workers", "3", "--timeout", "120", "chiefonboarding.wsgi:application"]

Custom Entrypoint Script (docker-entrypoint.sh)

Create a docker-entrypoint.sh file to handle initialization:

#!/bin/bash
set -e


echo "Starting ChiefOnboarding..."


# Wait for database to be ready
echo "Waiting for PostgreSQL..."
while ! nc -z $DATABASE_HOST ${DATABASE_PORT:-5432}; do
  sleep 1
done
echo "PostgreSQL is ready!"


# Run database migrations
echo "Running database migrations..."
python manage.py migrate --noinput


# Collect static files
echo "Collecting static files..."
python manage.py collectstatic --noinput


# Create superuser if it doesn't exist (optional)
if [ "$DJANGO_SUPERUSER_USERNAME" ] && [ "$DJANGO_SUPERUSER_PASSWORD" ] && [ "$DJANGO_SUPERUSER_EMAIL" ]; then
  echo "Creating superuser..."
  python manage.py shell << EOF
from django.contrib.auth import get_user_model
User = get_user_model()
if not User.objects.filter(username='$DJANGO_SUPERUSER_USERNAME').exists():
    User.objects.create_superuser('$DJANGO_SUPERUSER_USERNAME', '$DJANGO_SUPERUSER_EMAIL', '$DJANGO_SUPERUSER_PASSWORD')
    print('Superuser created.')
else:
    print('Superuser already exists.')
EOF
fi


# Execute the main command
exec "$@"

Important Notes:

  • ChiefOnboarding’s application listens on port 8000 internally
  • Klutch.sh will route external HTTP traffic to port 8000 in your container
  • The container includes the Django application, Gunicorn WSGI server
  • Celery workers should be configured separately or run in the same container with supervisord

Deploying to Klutch.sh

    1. Create Your Repository

      Create a new GitHub repository and add your Dockerfile and entrypoint script:

      Terminal window
      mkdir chiefonboarding-deployment
      cd chiefonboarding-deployment
      

      # Create Dockerfile
      cat > Dockerfile << 'EOF'
      FROM chiefonboarding/chiefonboarding:latest
      

      WORKDIR /app
      

      RUN mkdir -p /app/media /app/staticfiles
      

      EXPOSE 8000
      

      HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
        CMD curl -f http://localhost:8000/health/ || exit 1
      

      CMD ["sh", "-c", "python manage.py migrate && python manage.py collectstatic --noinput && gunicorn -b 0.0.0.0:8000 --workers 3 --timeout 120 chiefonboarding.wsgi:application"]
      EOF
      

      # Create .gitignore
      cat > .gitignore << 'EOF'
      .env
      .DS_Store
      __pycache__/
      *.pyc
      staticfiles/
      media/
      EOF
      

      # Create .dockerignore
      cat > .dockerignore << 'EOF'
      .git
      .gitignore
      .env
      README.md
      EOF
      

      # Initialize git and push
      git init
      git add .
      git commit -m "Initial ChiefOnboarding deployment setup"
      git remote add origin https://github.com/YOUR_USERNAME/chiefonboarding-deployment.git
      git push -u origin main

    2. Access the Klutch.sh Dashboard

      Navigate to klutch.sh/app and log in to your account.

    3. Create a New Project

      • Click “New Project” in the dashboard
      • Enter a project name (e.g., “HR Systems”)
      • Select your preferred region for deployment

    4. Create a New Application

      • Within your project, click “New App”
      • Name your application (e.g., “ChiefOnboarding”)
      • Connect your GitHub repository containing the Dockerfile

    5. Configure Build Settings

      Klutch.sh automatically detects the Dockerfile in your repository root. The build process will use this Dockerfile to create your container image.

    6. Set Up Persistent Storage

      ChiefOnboarding requires persistent storage for media files, uploads, and application data:

      • In the app settings, navigate to the “Volumes” section
      • Click “Add Volume”
      • Set the mount path to /app/media
      • Set the volume size (recommended: 10GB minimum for production)
      • Click “Add” to attach the volume
      • Optionally, add another volume for static files at /app/staticfiles (5GB)

      Critical: The /app/media directory stores:

      • Employee profile pictures
      • Uploaded documents and files
      • Custom resources and training materials
      • Integration files and exports

    7. Configure Environment Variables

      In the app settings, add the following required environment variables:

      Essential Variables:

      Terminal window
      SECRET_KEY=your-very-long-secret-key-min-50-chars
      DEBUG=False
      ALLOWED_HOSTS=your-app-name.klutch.sh,example-app.klutch.sh

      Database Configuration:

      Terminal window
      DATABASE_ENGINE=django.db.backends.postgresql
      DATABASE_HOST=your-postgres-host.klutch.sh
      DATABASE_PORT=8000
      DATABASE_NAME=chiefonboarding
      DATABASE_USER=chiefonboarding_user
      DATABASE_PASSWORD=your-secure-database-password

      Redis Configuration (Required for Celery):

      Terminal window
      REDIS_URL=redis://your-redis-host:6379/0
      CELERY_BROKER_URL=redis://your-redis-host:6379/0
      CELERY_RESULT_BACKEND=redis://your-redis-host:6379/0

      Email Configuration (SMTP):

      Terminal window
      EMAIL_HOST=smtp.gmail.com
      EMAIL_PORT=587
      EMAIL_USE_TLS=True
      EMAIL_HOST_USER=your-email@gmail.com
      EMAIL_HOST_PASSWORD=your-app-specific-password
      DEFAULT_FROM_EMAIL=noreply@yourdomain.com

      Slack Integration (Optional):

      Terminal window
      SLACK_BOT_TOKEN=xoxb-your-slack-bot-token
      SLACK_CLIENT_ID=your-slack-client-id
      SLACK_CLIENT_SECRET=your-slack-client-secret
      SLACK_SIGNING_SECRET=your-slack-signing-secret

      Application Configuration:

      Terminal window
      SITE_URL=https://your-app-name.klutch.sh
      BASE_URL=https://your-app-name.klutch.sh
      TIME_ZONE=America/New_York
      LANGUAGE_CODE=en-us

      Security Settings:

      Terminal window
      CSRF_TRUSTED_ORIGINS=https://your-app-name.klutch.sh
      SESSION_COOKIE_SECURE=True
      CSRF_COOKIE_SECURE=True

      Security Best Practice: Always use the “Secret” checkbox for sensitive values like SECRET_KEY, database passwords, API tokens, and SMTP passwords.

    8. Configure Traffic Settings

      • In the “Networking” section, select HTTP as the traffic type
      • Set the internal port to 8000 (ChiefOnboarding’s default port)
      • Enable automatic HTTPS/SSL (provided by Klutch.sh)

    9. Deploy the Application

      • Review all settings
      • Click “Deploy” to start the build process
      • Klutch.sh will:
        • Clone your repository
        • Detect the Dockerfile
        • Build the container image
        • Deploy to your selected region
        • Provision persistent storage
        • Configure networking and SSL

    10. Monitor Deployment Progress

      • View real-time build logs in the dashboard
      • Wait for the deployment status to show “Running”
      • Initial startup may take 2-3 minutes as Django runs migrations and collects static files

Once deployment completes, your ChiefOnboarding instance will be accessible at https://your-app-name.klutch.sh or your configured custom domain.

Database Setup and Configuration

ChiefOnboarding requires PostgreSQL for production deployments. SQLite is not recommended for production use.

Setting Up PostgreSQL

    1. Provision a PostgreSQL Database

      You can use:

      • A PostgreSQL instance deployed on Klutch.sh (follow the PostgreSQL deployment guide)
      • A managed PostgreSQL service (AWS RDS, Google Cloud SQL, DigitalOcean Managed Database)
      • Your own PostgreSQL server

    2. Create Application Database and User

      Connect to your PostgreSQL instance and create a database for ChiefOnboarding:

      CREATE DATABASE chiefonboarding;
      CREATE USER chiefonboarding_user WITH PASSWORD 'strong-secure-password';
      GRANT ALL PRIVILEGES ON DATABASE chiefonboarding TO chiefonboarding_user;
      

      -- Grant schema privileges (PostgreSQL 15+)
      \c chiefonboarding
      GRANT ALL ON SCHEMA public TO chiefonboarding_user;

    3. Configure Database Connection

      In your Klutch.sh app environment variables, set:

      Terminal window
      DATABASE_ENGINE=django.db.backends.postgresql
      DATABASE_HOST=your-postgres-host.klutch.sh
      DATABASE_PORT=8000
      DATABASE_NAME=chiefonboarding
      DATABASE_USER=chiefonboarding_user
      DATABASE_PASSWORD=strong-secure-password

      Note: If your PostgreSQL database is deployed on Klutch.sh with TCP traffic, use port 8000 for external connections.

    4. Test Database Connection

      After setting the environment variables, trigger a new deployment. Check the logs to ensure migrations run successfully:

      Terminal window
      # Look for these log messages:
      Running migrations...
      Operations to perform:
      Applying migrations...

Setting Up Redis for Celery

ChiefOnboarding uses Celery for background task processing (sending emails, Slack notifications, scheduled workflows). Redis is required as the message broker.

    1. Deploy Redis Instance

      Option A: Deploy Redis on Klutch.sh

      Option B: Use a managed Redis service

      • Redis Labs (cloud-hosted)
      • AWS ElastiCache
      • DigitalOcean Managed Redis

    2. Configure Redis Connection

      Add these environment variables to your ChiefOnboarding app:

      Terminal window
      REDIS_URL=redis://your-redis-host:6379/0
      CELERY_BROKER_URL=redis://your-redis-host:6379/0
      CELERY_RESULT_BACKEND=redis://your-redis-host:6379/0

      If Redis requires authentication:

      Terminal window
      REDIS_URL=redis://:password@your-redis-host:6379/0
      CELERY_BROKER_URL=redis://:password@your-redis-host:6379/0

    3. Start Celery Workers

      ChiefOnboarding requires Celery workers to process background tasks. You have two options:

      Option A: Single Container with Supervisord (simpler but less scalable)

      Update your Dockerfile to include supervisor:

      FROM chiefonboarding/chiefonboarding:latest
      

      RUN apt-get update && apt-get install -y supervisor && rm -rf /var/lib/apt/lists/*
      

      COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
      

      EXPOSE 8000
      

      CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]

      Create supervisord.conf:

      [supervisord]
      nodaemon=true
      

      [program:django]
      command=gunicorn -b 0.0.0.0:8000 --workers 3 chiefonboarding.wsgi:application
      autostart=true
      autorestart=true
      stderr_logfile=/var/log/django.err.log
      stdout_logfile=/var/log/django.out.log
      

      [program:celery]
      command=celery -A chiefonboarding worker -l info
      autostart=true
      autorestart=true
      stderr_logfile=/var/log/celery.err.log
      stdout_logfile=/var/log/celery.out.log
      

      [program:celerybeat]
      command=celery -A chiefonboarding beat -l info
      autostart=true
      autorestart=true
      stderr_logfile=/var/log/celerybeat.err.log
      stdout_logfile=/var/log/celerybeat.out.log

      Option B: Separate Celery Worker App (recommended for production)

      Deploy a second Klutch.sh app for Celery workers:

      • Use the same repository and Docker image
      • Override the CMD to run Celery instead of Gunicorn
      • Set environment variables to match your main app

      In the Celery worker app, use this Dockerfile:

      FROM chiefonboarding/chiefonboarding:latest
      

      CMD ["celery", "-A", "chiefonboarding", "worker", "-l", "info", "--concurrency", "4"]

Setting Up Persistent Volumes

Persistent storage is critical for maintaining employee data, uploaded documents, and configuration files across deployments and restarts.

Required Mount Paths

Configure persistent volumes in the Klutch.sh dashboard:

  • Mount Path: /app/media

  • Recommended Size: 10GB minimum (20GB+ for production with many employees)

  • Mount Path (optional): /app/staticfiles

  • Recommended Size: 5GB

What Gets Stored

The /app/media directory contains:

/app/media/
├── profile_photos/      # Employee profile pictures
├── documents/           # Uploaded onboarding documents
├── resources/           # Training materials and guides
├── badges/              # Achievement badges and icons
└── exports/            # Data exports and reports

Backup Strategy

For production deployments, implement regular backups:

    1. Schedule Volume Snapshots

      Use Klutch.sh’s volume snapshot feature (if available) to create regular backups of the media volume.

    2. Database Backups

      Regularly backup your PostgreSQL database:

      Terminal window
      pg_dump -h host -U chiefonboarding_user -d chiefonboarding > chiefonboarding-backup-$(date +%Y%m%d).sql

    3. Automated Backup Script

      Create a backup script that runs daily:

      #!/bin/bash
      DATE=$(date +%Y%m%d)
      

      # Backup database
      pg_dump -h $DATABASE_HOST -U $DATABASE_USER -d $DATABASE_NAME > /backups/db-$DATE.sql
      

      # Compress and upload to S3 or backup service
      tar -czf /backups/chiefonboarding-$DATE.tar.gz /backups/db-$DATE.sql /app/media
      

      # Upload to S3 (requires AWS CLI)
      aws s3 cp /backups/chiefonboarding-$DATE.tar.gz s3://your-backup-bucket/
      

      # Clean up old backups (keep last 30 days)
      find /backups -type f -mtime +30 -delete

Environment Variables Reference

Required Variables

VariableDescriptionExample
SECRET_KEYDjango secret key for security (min 50 chars)django-insecure-a1b2c3d4e5...
DEBUGDebug mode (must be False in production)False
ALLOWED_HOSTSComma-separated list of allowed hostnamesapp.klutch.sh,yourdomain.com
DATABASE_ENGINEDatabase backenddjango.db.backends.postgresql
DATABASE_HOSTDatabase hostnamepostgres.klutch.sh
DATABASE_PORTDatabase port8000
DATABASE_NAMEDatabase namechiefonboarding
DATABASE_USERDatabase usernamechiefonboarding_user
DATABASE_PASSWORDDatabase passwordsecure-password-here

Redis & Celery Variables

VariableDescriptionExample
REDIS_URLRedis connection URLredis://host:6379/0
CELERY_BROKER_URLCelery message brokerredis://host:6379/0
CELERY_RESULT_BACKENDCelery result backendredis://host:6379/0

Email Configuration

VariableDescriptionExample
EMAIL_HOSTSMTP server hostnamesmtp.gmail.com
EMAIL_PORTSMTP server port587
EMAIL_USE_TLSUse TLS encryptionTrue
EMAIL_HOST_USERSMTP usernameyour-email@gmail.com
EMAIL_HOST_PASSWORDSMTP passwordapp-specific-password
DEFAULT_FROM_EMAILDefault sender emailnoreply@yourdomain.com

Slack Integration (Optional)

VariableDescription
SLACK_BOT_TOKENSlack bot OAuth token
SLACK_CLIENT_IDSlack app client ID
SLACK_CLIENT_SECRETSlack app client secret
SLACK_SIGNING_SECRETSlack request signing secret

Application Settings

VariableDescriptionDefault
SITE_URLPublic URL of your instancehttps://app.klutch.sh
BASE_URLBase URL for linkshttps://app.klutch.sh
TIME_ZONEServer timezoneUTC
LANGUAGE_CODELanguage codeen-us
CSRF_TRUSTED_ORIGINSTrusted origins for CSRFhttps://app.klutch.sh

Slack Integration Setup

ChiefOnboarding integrates with Slack to send onboarding notifications, task reminders, and welcome messages to new employees.

    1. Create Slack App

      • Go to api.slack.com/apps
      • Click “Create New App” → “From scratch”
      • Enter app name: “ChiefOnboarding”
      • Select your workspace

    2. Configure OAuth Scopes

      • Navigate to “OAuth & Permissions”
      • Add Bot Token Scopes:
        • chat:write
        • chat:write.public
        • users:read
        • users:read.email
        • channels:read
        • groups:read

    3. Install App to Workspace

      • Click “Install to Workspace”
      • Authorize the requested permissions
      • Copy the “Bot User OAuth Token” (starts with xoxb-)

    4. Get App Credentials

      • Navigate to “Basic Information”
      • Copy:
        • Client ID
        • Client Secret
        • Signing Secret

    5. Configure Environment Variables

      Add these to your ChiefOnboarding app on Klutch.sh:

      Terminal window
      SLACK_BOT_TOKEN=xoxb-your-token-here
      SLACK_CLIENT_ID=123456789.123456789
      SLACK_CLIENT_SECRET=abcdef123456
      SLACK_SIGNING_SECRET=your-signing-secret

    6. Enable Event Subscriptions (Optional)

      • In Slack App settings, go to “Event Subscriptions”
      • Enable Events
      • Set Request URL: https://your-app-name.klutch.sh/slack/events/
      • Subscribe to bot events: message.channels, app_mention

Custom Domain Configuration

To use your own domain with ChiefOnboarding on Klutch.sh:

    1. Add Domain in Dashboard

      • Navigate to your ChiefOnboarding app in the Klutch.sh dashboard
      • Go to “Domains” section
      • Click “Add Custom Domain”
      • Enter your domain (e.g., onboarding.yourdomain.com)

    2. Configure DNS Records

      Add a CNAME record in your DNS provider:

      Type: CNAME
      Name: onboarding (or your subdomain)
      Value: your-app-name.klutch.sh
      TTL: 3600

    3. Enable SSL/TLS

      Klutch.sh automatically provisions and manages SSL certificates for your custom domain using Let’s Encrypt.

    4. Update ChiefOnboarding Configuration

      Update environment variables:

      Terminal window
      SITE_URL=https://onboarding.yourdomain.com
      BASE_URL=https://onboarding.yourdomain.com
      ALLOWED_HOSTS=onboarding.yourdomain.com,your-app-name.klutch.sh
      CSRF_TRUSTED_ORIGINS=https://onboarding.yourdomain.com

    5. Verify Configuration

      • Wait for DNS propagation (usually 5-15 minutes)
      • Visit https://onboarding.yourdomain.com
      • Verify SSL certificate is active

For detailed domain configuration, see the Klutch.sh Custom Domains guide.

Getting Started with ChiefOnboarding

After deploying your ChiefOnboarding instance, follow these steps to set up your first onboarding workflow:

Initial Setup

    1. Access Your Instance

      Navigate to https://your-app-name.klutch.sh (or your custom domain).

    2. Create Administrator Account

      If you didn’t set DJANGO_SUPERUSER_* environment variables:

      • Click “Sign up” to create the first admin account
      • Enter your email, full name, and password
      • Complete the registration

      Or access the container and create a superuser manually:

      Terminal window
      python manage.py createsuperuser

    3. Configure Organization Settings

      • Log in to the admin panel
      • Navigate to Settings
      • Configure:
        • Company name and logo
        • Default timezone
        • Email templates
        • Slack workspace connection

    4. Set Up Teams and Departments

      • Create departments (e.g., Engineering, Sales, Marketing)
      • Add team members and managers
      • Assign roles and permissions

Creating Your First Onboarding Workflow

    1. Create a New Sequence

      • Navigate to “Sequences” in the dashboard
      • Click “Create New Sequence”
      • Enter sequence name (e.g., “Engineering Onboarding”)
      • Choose sequence type:
        • Pre-boarding (before first day)
        • First day
        • First week
        • First month

    2. Add Tasks to Sequence

      Click “Add Task” and configure:

      Example Task 1: Complete HR Paperwork

      Name: Complete employment forms
      Description: Fill out W-4, I-9, and direct deposit forms
      Assigned to: New hire
      Due: Day 1, 9:00 AM
      Type: Form submission
      Priority: High

      Example Task 2: Set Up Development Environment

      Name: Install development tools
      Description: Install VS Code, Node.js, Git, and Docker
      Assigned to: New hire
      Due: Day 1, 2:00 PM
      Type: Checklist
      Priority: Medium

      Example Task 3: Meet with Manager

      Name: 1:1 with Manager
      Description: 30-minute intro meeting to discuss role and expectations
      Assigned to: Manager
      Due: Day 1, 11:00 AM
      Type: Meeting
      Priority: High

    3. Configure Notifications

      For each task, set up:

      • Email notifications (send to employee, manager, or both)
      • Slack messages (DM or channel)
      • Reminder frequency (1 day before, same day, overdue)

    4. Add Resources

      Attach helpful resources to tasks:

      • PDF documents (employee handbook, policies)
      • Links to internal wikis or documentation
      • Video tutorials
      • Contact information

    5. Set Conditions (Optional)

      Create conditional logic:

      • If task A is completed, trigger task B
      • If role = “Developer”, show additional technical setup tasks
      • If location = “Remote”, skip office tour

    6. Save and Activate Sequence

      • Review all tasks and settings
      • Click “Save”
      • Enable the sequence by toggling it to “Active”

Sample Onboarding Workflow

Here’s a complete example of a software engineering onboarding workflow:

Pre-boarding (Week before start date):

  • ✉️ Welcome email with company info
  • 📋 Send equipment preference survey
  • 📝 Complete I-9 and W-4 forms online
  • 🎫 Create accounts (email, Slack, GitHub, Jira)

Day 1:

  • 🏢 Office tour (or virtual tour)
  • 💻 Receive laptop and equipment
  • 👥 Meet the team (introductions)
  • 📖 Review employee handbook
  • 🔐 Security and compliance training
  • 🍕 Lunch with team

Week 1:

  • 🛠️ Set up development environment
  • 📚 Complete technical onboarding docs
  • 🏗️ Deploy first “Hello World” to production
  • 🗣️ 1:1 meetings with key stakeholders
  • 📊 Review team’s current projects and roadmap

Month 1:

  • 🎯 Complete first project milestone
  • 📝 Submit first code review
  • 🤝 Pair programming with senior developer
  • 🧪 Learn testing and CI/CD processes
  • 📈 30-day check-in with manager

Onboarding a New Employee

    1. Add New Employee

      • Navigate to “Employees” → “Add New”
      • Enter employee information:
        • Full name
        • Email address
        • Job title
        • Department
        • Manager
        • Start date

    2. Assign Onboarding Sequence

      • Select one or more sequences to assign
      • Choose start date (usually first day of work)
      • Customize tasks if needed

    3. Send Welcome Email

      ChiefOnboarding automatically sends a welcome email with:

      • Login credentials
      • Overview of onboarding tasks
      • First day schedule
      • Important contacts

    4. Track Progress

      • Monitor task completion in real-time
      • View progress dashboard
      • Receive notifications when tasks are completed or overdue
      • Send reminders manually if needed

    5. Collect Feedback

      After onboarding completion:

      • Send feedback survey
      • Review what worked well
      • Identify areas for improvement
      • Update sequences based on feedback

Production Best Practices

Security Hardening

    1. Use Strong Secret Key

      Generate a secure Django secret key:

      Terminal window
      python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'

    2. Enable HTTPS Only

      Ensure these environment variables are set:

      Terminal window
      SESSION_COOKIE_SECURE=True
      CSRF_COOKIE_SECURE=True
      SECURE_SSL_REDIRECT=True

    3. Restrict Admin Access

      • Use strong passwords for admin accounts
      • Enable two-factor authentication (2FA)
      • Limit admin privileges to only necessary users
      • Regularly audit user access

    4. Regular Security Updates

      • Monitor for ChiefOnboarding updates

      • Update your Dockerfile to use specific version tags:

        FROM chiefonboarding/chiefonboarding:v2.5.0

      • Test updates in staging before production

      • Subscribe to security advisories

    5. Database Security

      • Use SSL/TLS for database connections
      • Restrict database access to only the application
      • Use strong database passwords
      • Regular database backups

Performance Optimization

    1. Configure Celery Workers

      Adjust worker concurrency based on workload:

      Terminal window
      celery -A chiefonboarding worker -l info --concurrency=8

    2. Enable Redis Caching

      Add caching configuration:

      Terminal window
      REDIS_CACHE_URL=redis://your-redis-host:6379/1

    3. Optimize Database Queries

      • Create database indexes for frequently queried fields
      • Use Django’s select_related() and prefetch_related()
      • Monitor slow queries with Django Debug Toolbar (dev only)

    4. Configure Gunicorn Workers

      Adjust workers based on CPU cores:

      CMD ["gunicorn", "-b", "0.0.0.0:8000", "--workers", "4", "--threads", "2", "--timeout", "120", "chiefonboarding.wsgi:application"]

      Rule of thumb: workers = (2 * CPU cores) + 1

    5. Use CDN for Static Assets

      Configure a CDN for static files:

      Terminal window
      STATIC_URL=https://cdn.yourdomain.com/static/

    6. Monitor Resource Usage

      • Track CPU, memory, and disk usage in Klutch.sh dashboard
      • Set up alerts for high resource consumption
      • Scale vertically (larger instance) if needed

Backup and Disaster Recovery

    1. Automated Database Backups

      Set up daily PostgreSQL backups:

      backup.sh
      #!/bin/bash
      DATE=$(date +%Y%m%d_%H%M%S)
      BACKUP_DIR="/backups"
      

      pg_dump -h $DATABASE_HOST -U $DATABASE_USER -d $DATABASE_NAME \
        | gzip > $BACKUP_DIR/chiefonboarding-$DATE.sql.gz
      

      # Upload to S3
      aws s3 cp $BACKUP_DIR/chiefonboarding-$DATE.sql.gz \
        s3://your-backup-bucket/databases/
      

      # Keep only last 30 days locally
      find $BACKUP_DIR -name "*.sql.gz" -mtime +30 -delete

    2. Volume Snapshots

      • Schedule regular snapshots of the /app/media volume
      • Store snapshots in multiple regions
      • Test restore procedures regularly

    3. Configuration Backup

      • Store environment variables in secure password manager
      • Document all configuration settings
      • Keep infrastructure-as-code in version control

    4. Disaster Recovery Plan

      Document steps to restore from backups:

      1. Provision new Klutch.sh app
      2. Restore database from latest backup
      3. Restore media files from volume snapshot
      4. Configure environment variables
      5. Verify application functionality
      6. Update DNS to point to new instance

Troubleshooting Common Issues

Application Won’t Start

Symptoms: Container starts but ChiefOnboarding UI is not accessible

Solutions:

    1. Check logs in the Klutch.sh dashboard for errors

    2. Verify all required environment variables are set

    3. Ensure SECRET_KEY is at least 50 characters

    4. Check database connectivity:

      Terminal window
      python manage.py dbshell

    5. Verify Redis is accessible:

      Terminal window
      redis-cli -h $REDIS_HOST ping

    6. Run migrations manually:

      Terminal window
      python manage.py migrate

Database Connection Errors

Symptoms: “Unable to connect to database” errors in logs

Solutions:

    1. Verify database credentials in environment variables

    2. Check DATABASE_HOST and DATABASE_PORT are correct

    3. If using Klutch.sh PostgreSQL with TCP, ensure port is 8000

    4. Test connection from container:

      Terminal window
      psql -h $DATABASE_HOST -p $DATABASE_PORT -U $DATABASE_USER -d $DATABASE_NAME

    5. Verify database user has necessary permissions

    6. Check network connectivity between services

Celery Tasks Not Processing

Symptoms: Emails not sending, Slack notifications not appearing

Solutions:

    1. Check if Celery worker is running:

      Terminal window
      celery -A chiefonboarding inspect active

    2. Verify Redis connection:

      Terminal window
      redis-cli -h $REDIS_HOST ping

    3. Check Celery logs for errors

    4. Restart Celery workers

    5. Verify CELERY_BROKER_URL matches REDIS_URL

Email Not Sending

Symptoms: Onboarding emails not delivered

Solutions:

    1. Check email configuration in environment variables

    2. Verify SMTP credentials are correct

    3. Test SMTP connection:

      Terminal window
      python manage.py sendtestemail your-email@example.com

    4. Check if EMAIL_USE_TLS is set correctly (True for port 587)

    5. For Gmail, use an App Password instead of your regular password

    6. Check spam folder

    7. Review Celery worker logs for email task errors

Slack Integration Not Working

Symptoms: Slack notifications not appearing

Solutions:

    1. Verify Slack environment variables are set correctly
    2. Check SLACK_BOT_TOKEN starts with xoxb-
    3. Ensure bot is invited to channels where it should post
    4. Verify OAuth scopes are correct in Slack App settings
    5. Test connection in ChiefOnboarding admin panel
    6. Check Slack signing secret matches
    7. Review Celery logs for Slack API errors

Static Files Not Loading

Symptoms: Missing CSS, images not displaying

Solutions:

    1. Run collectstatic command:

      Terminal window
      python manage.py collectstatic --noinput

    2. Verify STATIC_ROOT is set correctly

    3. Check volume mount for /app/staticfiles

    4. Ensure web server (Gunicorn) can access static directory

    5. Configure STATIC_URL correctly:

      Terminal window
      STATIC_URL=/static/

Scaling Your ChiefOnboarding Deployment

As your organization grows, consider these scaling strategies:

Vertical Scaling

Increase resources for your ChiefOnboarding instance:

  • Upgrade to a larger instance type in the Klutch.sh dashboard
  • Increase persistent volume size if storage is constrained
  • Recommended specs:
    • Small (< 100 employees): 2 CPU, 4GB RAM
    • Medium (100-500 employees): 4 CPU, 8GB RAM
    • Large (500+ employees): 8+ CPU, 16+ GB RAM

Horizontal Scaling

For very large deployments:

  • Deploy separate Celery worker instances
  • Use a load balancer for multiple web app instances
  • Implement read replicas for PostgreSQL
  • Use Redis cluster for caching

Database Optimization

  • Enable connection pooling (PgBouncer)
  • Create indexes on frequently queried fields
  • Archive old completed sequences
  • Regular VACUUM and ANALYZE

Migration from Self-Hosted to Klutch.sh

If you’re migrating from an existing ChiefOnboarding installation:

    1. Backup Existing Data

      Export your database:

      Terminal window
      python manage.py dumpdata > chiefonboarding-data.json
      

      # Or use pg_dump
      pg_dump -h localhost -U user chiefonboarding > backup.sql

    2. Export Media Files

      Copy all uploaded files:

      Terminal window
      tar -czf media-backup.tar.gz /path/to/media/

    3. Deploy New Instance on Klutch.sh

      Follow the deployment steps in this guide

    4. Restore Database

      Import your data:

      Terminal window
      python manage.py loaddata chiefonboarding-data.json
      

      # Or restore from SQL dump
      psql -h host -U user -d chiefonboarding < backup.sql

    5. Upload Media Files

      Extract and upload to the persistent volume:

      Terminal window
      tar -xzf media-backup.tar.gz -C /app/media/

    6. Update Configuration

      • Update SITE_URL and BASE_URL
      • Configure email and Slack with new settings
      • Update any webhook URLs

    7. Test Thoroughly

      • Verify all employees are present
      • Check sequences and tasks
      • Test email and Slack notifications
      • Confirm file uploads work

    8. Update DNS

      Point your domain to the new Klutch.sh deployment

Advanced Customization

Custom Email Templates

ChiefOnboarding supports custom email templates:

    1. Create Template Files

      Create HTML email templates in your repository:

      templates/emails/welcome.html
      <!DOCTYPE html>
      <html>
      <head>
          <style>
              body { font-family: Arial, sans-serif; }
              .header { background-color: #4CAF50; color: white; padding: 20px; }
          </style>
      </head>
      <body>
          <div class="header">
              <h1>Welcome to {{ company_name }}!</h1>
          </div>
          <p>Hi {{ employee_name }},</p>
          <p>We're excited to have you join our team!</p>
      </body>
      </html>

    2. Update Dockerfile to Include Templates

      FROM chiefonboarding/chiefonboarding:latest
      

      COPY templates/ /app/templates/
      

      EXPOSE 8000
      CMD ["gunicorn", "-b", "0.0.0.0:8000", "chiefonboarding.wsgi:application"]

    3. Configure Template Path

      Add environment variable:

      Terminal window
      TEMPLATE_DIR=/app/templates

Custom Branding

Customize ChiefOnboarding’s appearance:

    1. Upload Company Logo

      • Log in to admin panel
      • Navigate to Settings → Branding
      • Upload logo (recommended: 200x50px PNG)

    2. Configure Brand Colors

      Add CSS customization:

      custom.css
      :root {
        --primary-color: #4CAF50;
        --secondary-color: #45a049;
        --accent-color: #FFC107;
      }

    3. Custom Welcome Page

      Create a custom landing page for new hires with your branding, company values, and culture information.

Cost Optimization Tips

  • Right-size your instance: Start with a smaller instance and scale up based on usage
  • Use efficient Celery workers: Monitor task queue and adjust worker count
  • Implement task retention: Delete old completed tasks to save database space
  • Optimize media storage: Compress images and documents before upload
  • Archive inactive employees: Move completed onboarding data to cold storage
  • Monitor resource usage: Use Klutch.sh monitoring to identify optimization opportunities

Example Deployment Repository

For a complete working example, reference this sample repository structure:

chiefonboarding-klutch/
├── Dockerfile
├── docker-entrypoint.sh
├── supervisord.conf
├── .dockerignore
├── .gitignore
├── .env.example
└── README.md

Dockerfile:

FROM chiefonboarding/chiefonboarding:v2.5.0


WORKDIR /app


RUN apt-get update && apt-get install -y supervisor curl && \
    rm -rf /var/lib/apt/lists/*


RUN mkdir -p /app/media /app/staticfiles


COPY docker-entrypoint.sh /app/docker-entrypoint.sh
COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf


RUN chmod +x /app/docker-entrypoint.sh


EXPOSE 8000


HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:8000/health/ || exit 1


ENTRYPOINT ["/app/docker-entrypoint.sh"]
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]

.env.example:

Terminal window
# Django
SECRET_KEY=change-me-to-a-long-random-string-min-50-chars
DEBUG=False
ALLOWED_HOSTS=your-app-name.klutch.sh


# Database
DATABASE_ENGINE=django.db.backends.postgresql
DATABASE_HOST=postgres-host.klutch.sh
DATABASE_PORT=8000
DATABASE_NAME=chiefonboarding
DATABASE_USER=chiefonboarding_user
DATABASE_PASSWORD=change-me


# Redis
REDIS_URL=redis://redis-host:6379/0
CELERY_BROKER_URL=redis://redis-host:6379/0
CELERY_RESULT_BACKEND=redis://redis-host:6379/0


# Email
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password
DEFAULT_FROM_EMAIL=noreply@yourdomain.com


# Application
SITE_URL=https://your-app-name.klutch.sh
BASE_URL=https://your-app-name.klutch.sh
TIME_ZONE=UTC
CSRF_TRUSTED_ORIGINS=https://your-app-name.klutch.sh

README.md:

# ChiefOnboarding on Klutch.sh


Production-ready ChiefOnboarding deployment for employee onboarding automation.


## Quick Start


1. Clone this repository
2. Copy `.env.example` to `.env` and configure
3. Push to GitHub
4. Deploy on Klutch.sh following the official guide


## Requirements


- PostgreSQL database
- Redis instance
- SMTP server for emails
- (Optional) Slack workspace


## Support


See the full deployment guide at docs.klutch.sh

Additional Resources

Conclusion

Deploying ChiefOnboarding on Klutch.sh provides a powerful, scalable platform for automating employee onboarding without the complexity of managing infrastructure. With automatic Dockerfile detection, persistent storage, secure environment management, and production-ready configurations, you can focus on creating exceptional onboarding experiences for your new hires.

Whether you’re onboarding software engineers, sales representatives, or remote employees across multiple departments, ChiefOnboarding on Klutch.sh offers the reliability and flexibility you need. Start automating your employee onboarding today and create a seamless first impression that sets new hires up for success from day one.

For additional help or questions, reach out to the ChiefOnboarding community or Klutch.sh support.