Self-Hosting Installation Guide

Cloud or Self-Hosting?

Before choosing self-hosting, consider the advantages of our Cloud offering:

Instant Setup: Get started within minutes. No need to configure servers or install dependencies.
Automatic Updates: Always stay up to date with the latest features, security patches, and performance improvements.
High Availability & Scalability: Hosted on reliable infrastructure with built-in redundancy and automatic scaling to handle your growing usage.
Security Best Practices: End-to-end encryption, regular audits, and managed backups to keep your data safe.
Priority Support: Access to premium support, including hands-on onboarding and faster response times.

For most users, the Cloud version is the fastest and easiest way to start using the platform.

Choose self-hosting only if you require custom infrastructure or full control.

Get Started with the Cloud Version

Installation Method:

This guide will help you set up your self-hosted instance of Viashell using Docker Compose.

To run a self-hosted instance of Viashell, you will need the following:

Docker: Our application is built using Docker, so you will need to have Docker installed on your server.
Postgres Database: A relational database to store your data.
Object Storage: A S3-compatible storage solution for your files. (AWS S3, DigitalOcean Spaces, or MinIO)

Sample docker-compose.yaml:

services:
  app:
    image: viashell/viashell:latest
    container_name: viashell
    ports:
      - "80:80"
      - "1883:1883" # Used for agents
    environment:
      - PG_DB_HOST=postgres
      - PG_DB_PORT=5432
      - PG_DB_USER=your_pg_user
      - PG_DB_PASSWORD=your_pg_password
      - PG_DB_NAME=viashelldb
      - MINIO_HOST=object-storage # s3.amazonaws.com for AWS S3
      - MINIO_PORT=9000 # Not needed for AWS S3
      - MINIO_KEY_ID=your_minio_user # your AWS Access Key ID
      - MINIO_KEY_SECRET=your_minio_password # your AWS Secret Access Key
      
      # Modify in production :start
      - USE_INSECURE=true # Allow insecure connections (HTTP) for testing purposes only
      - ROOT_HOST=localhost:80 # Used for agents and email redirection (do not add http:// or https://)
      - ENCRYPTION_KEY=01234567890123456789012345678901 # 32 characters long
      # Modify in production :end
      
      # Remove comment to enable email notifications :start
      #- SMTP_HOST=smtp.your-email-provider.com
      #- SMTP_PORT=587 # or 465 for SSL
      #- SMTP_USER=your_smtp_provider_user
      #- SMTP_PASSWORD=your_smtp_provider_password
      #- SMTP_FROM=contact@your-company.com
      # Remove comment to enable email notifications :end
      
  # The below services are for development and testing purposes only.
  # Use your own Postgres and Object Storage in production.
  postgres:
    image: postgres:16
    container_name: viashell-db
    environment:
      - POSTGRES_USER=your_pg_user
      - POSTGRES_PASSWORD=your_pg_password
      - POSTGRES_DB=viashelldb
      
  object-storage:
    image: minio/minio:latest
    container_name: viashell-minio
    environment:
      - MINIO_ROOT_USER=your_minio_user
      - MINIO_ROOT_PASSWORD=your_minio_password
      - MINIO_BUCKET=viashell
    entrypoint: sh
    command: -c 'mkdir -p /data/viashell && /usr/bin/minio server /data --console-address ":9001"'

Run the command below to start Viashell and all related services.

$ docker-compose -f docker-compose.yaml up

Your Viashell instance should now be running on port 80.

To access your instance, visit http://localhost:80. The default admin credentials are: admin / change_me

In a production environment:

Remove the USE_INSECURE environment variable to enforce secure connections (HTTPS).
Set up a reverse proxy (like Nginx or Traefik) to handle SSL termination and routing.
Generate a random 32-character encryption key and set it in the ENCRYPTION_KEY environment variable.