Setting up a Linux server to be your Enpass Hub

If you’re setting up a Self-Hosted Enpass Hub for the first time, this process is step 1 of 8.

 

In this guide, we’ll outline the process of deploying the Enpass Hub on your own servers using Docker Compose. These instructions assume a basic knowledge of Docker, Docker Compose, and server management.

The first step is to set up and configure a Linux server for your Enpass Hub, which includes...

  • Updating your server
  • Installing nginx and installing an SSL certificate to serve Hub connections securely
  • installing Docker and Docker Compose
  • Creating a Docker Compose configuration
  • Setting up specific environment variables
  • Deployment and testing

 

Prerequisites:

A Linux server (Ubuntu 20.04 LTS or newer is recommended) with at least:

  • 2 GHz dual-core processor
  • 4 GB of RAM
  • 20 GB of free disk space

Enpass Hub uses a PostgreSQL database for persisting data. In this guide we will run Postgres SQL server with Docker Compose. If you already have a PostgresSQL database on another machine, you can use that database instead.

 

Step 1: Update your server

  1. Ensure your server is up-to-date by running the following commands: 
    sudo apt update
sudo apt upgrade -y

 

Step 2: Install reverse proxy and SSL/TLS Certificate

  1. Install nginx: 
    sudo apt install nginx
  2. If you don't have SSL/TLS certificates already, install Certbot, a tool for obtaining and managing SSL/TLS certificates from Let's Encrypt (a free SSL provider): 
    sudo apt install certbot python3-certbot-nginx
  3. Use Certbot to obtain a certificate for your domain, replacing red text with the actual URL of your Enpass Hub install: 
    sudo certbot --nginx -d your-domain.com

 

Step 3: Install Docker

  1. Install Docker Engine and the Docker Compose plugin, if you have not already.

Alternatively, you can use the following steps in your terminal (up to date as of September 12, 2023):


  1. Add Docker's official GPG key: 
    sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
  2. Add the repository to Apt sources: 
    echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] 
  https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  
  sudo apt-get update
  3. Install docker and docker-compose: 
    sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

 

Step 4: Enable Docker for a non-root user

  1. Enable use of Docker for normal user: 
    sudo usermod -aG docker ${USER}
  2. Log out and log back in, so that your group membership is re-evaluated.
  3. To verify that you've been added to the Docker group, you can run: 
    id -nG

 

Step 5: Create a Docker Compose configuration

You can find a full docker compose example configuration on our Github Repository:

This guide will use a subset of that configuration, following these steps:

  • mkdir enpass-hub
  • cd enpass-hub
  • touch docker-compose.yml

  1. Save the following configuration in docker-compose.yml, replacing the red text with your own parameters. 
    version: '3.4'

services:
  db:
    image: postgres:14-alpine
    expose:
      - "5432"
    environment:
      - POSTGRES_DB=${HUB_DB_NAME}
      - POSTGRES_USER=${HUB_DB_USERNAME}
      - POSTGRES_PASSWORD_FILE=/run/secrets/hub_db_password
    networks:
      - main
    volumes:
      # postgres data persistentance in extra volume
      - postgres_data:/var/lib/postgresql/data
    
    secrets:
      - hub_db_password
    restart: on-failure
  
  redis:
    image: redis
    networks:
      - main

  app:
    image: public.ecr.aws/enpass/hub-server:latest
    command: ["sh", "-c", "nc -z db 5432 && entrypoint.sh"]
    env_file: .env
    environment:
      - HUB_SECRET_KEY_FILE=/run/secrets/hub_secret_key
      - HUB_DB_PASSWORD_FILE=/run/secrets/hub_db_password
      - EMAIL_HOST_PASSWORD_FILE=/run/secrets/email_host_password

    depends_on:
      - db
      - redis
    ports:
      - "8000:8000"
    volumes:
      # copy static files to local folder on host
      - ./static:/usr/src/app/static/
    hostname: app
    networks:
      - main
    secrets:
      - hub_db_password
      - hub_secret_key
      - email_host_password
    restart: on-failure

volumes:
  static:
  postgres_data: 
    external: true
  
networks:
  main:

secrets:
  hub_db_password:
    file: hub_db_password.txt
  hub_secret_key:
    file: hub_secret_key.txt
  email_host_password:
    file: email_host_password.txt

This configuration ensures that the application service...

  • Includes environment variables specified in the .env file, as configured in next step.
  • Includes Docker Compose secret-environment variables configured in next step.
  • Exposes port 8000, where the application service listens for incoming requests.
  • Places the application's static files in /usr/src/app/static/. These files can be served via proxy server using the /static path.

You can modify this sample configuration according to your needs and place it in an appropriate directory.

 

Step 6: Set up environment variables

For defining your configuration, create a .env file in the same directory as your Docker Compose file. (Here's an example .env file.)

Variables you may need to define include:

Application Secrets and Host Settings

Your Hub will need a comma-separated ALLOWED_HOSTS list of host/domain names associated with the Enpass Hub server.

Replace the red text with your own parameters.

ALLOWED_HOSTS=localhost,hub.example.com

Database Settings

Enpass Hub requires a PostgreSQL database to function, and these settings determine the parameters for the connection to that database. They include the hostname or IP address of the database server, the database name, and the credentials for accessing the database.

Replace the red text with your own parameters.

HUB_DB_HOSTNAME=db
HUB_DB_NAME=hub-database
HUB_DB_USERNAME=my-username
HUB_DB_PORT=5432

Email Settings

These settings are essential for the application's communication mechanisms. Enpass Hub uses these configurations to send out emails, such as notifications and one-time passwords (OTPs), used to verify users during login. These variables specify the outgoing mail server's details, including the hostname, user credentials, port, and the type of security to be used for the connection. The SERVER_EMAIL and DEFAULT_FROM_EMAIL define the sender address for system-generated and outgoing emails.

Replace the red text with your own parameters.

EMAIL_HOST=smtp.example.com
EMAIL_HOST_USER=mysmtpusername
EMAIL_PORT=25
EMAIL_USE_TLS=True
SERVER_EMAIL=noreply@example.com
DEFAULT_FROM_EMAIL=noreply@example.com

Message Queue Settings

This setting provides the URL or connection details for the Redis message broker used in the application's message queue system.

Replace the red text with your own parameters.

BROKER_URL=redis://<redis-broker-url>:6379/0

Static files from Enpass CDN

Though the static files will be copied into /usr/src/app/static/, you will need additional configurations to serve via nginx. You can use static files directly from our CDN for convenience.

HUB_STATIC_URL=https://hub-static.enpass.io/static/

Secrets and passwords

Use Docker Compose implementation of secrets injection into container.

  • Generate a random key, used for cryptographic signing (typically for session cookies) and stored the appropriate file: 
    tr -dc '[A-Za-z0-9!"#$%&(){}*+,-./:;<=>?@^_`~|]' < /dev/urandom | head -c 50 > hub_secret_key.txt
  • Create a file named hub_db_password.txt and use it to store your Enpass Hub PostgreSQL password.
  • Create a file named email_host_password.txt and use it to store your Email host password.

 

Step 7: Deploy the Application

With the Docker Compose and environment files ready, you can now deploy the application.

Start and test services
  1. Create a persistent volume for your database: 
    docker volume create --name=postgres_data
  2. Test the service by starting all services defined in your Docker Compose file: 
    docker compose up
  3. If all looks perfect, press CTRL+C and exit.

Create a Systemd Service

To manage your Enpass Hub service, create a systemd service file.

  1. Create a file named enpass-hub.service in /etc/systemd/system/: 
    sudo nano /etc/systemd/system/enpass-hub.service
  2. Add this content to the file, replacing red text with your actual path and username: 
    [Unit]
Description=Enpass Hub service with docker compose
PartOf=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=true
WorkingDirectory=/home/ubuntu/enpass-hub
ExecStart=/usr/bin/docker compose up -d --remove-orphans
ExecStop=/usr/bin/docker compose down
User=ubuntu

[Install]
WantedBy=multi-user.target
  3. Enable and start the service: 
    sudo systemctl daemon-reload
sudo systemctl enable enpass-hub
sudo systemctl start enpass-hub

Configure nginx

Create a new nginx configuration file for your Enpass Hub application.

  1. Create a configuration file in the /etc/nginx/sites-available/ directory: 
    sudo nano /etc/nginx/sites-available/enpass-hub
  2. Add this content to the file, replacing red text with your actual path and username: 
    server {
    listen 80;
    server_name your-domain.com www.your-domain.com;
    # Redirect HTTP requests to HTTPS
    return 301 https://your-domain.com$request_uri;
}

server {
    # don't send the nginx version number in error pages and Server header
    server_tokens off;

    listen 443 ssl;
    server_name your-domain.com www.your-domain.com;

    #add Security headers
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "0";
    add_header Referrer-Policy "no-referrer";
    add_header Cache-Control "no-cache, no-store, must-revalidate";

    add_header Permissions-Policy "geolocation=(),midi=(),notifications=(),push=(),
    sync-xhr=(),microphone=(),camera=(),magnetometer=(),gyroscope=(),speaker=(self),
    vibrate=(),fullscreen=(self),payment=()";
    
    add_header Strict-Transport-Security "max-age=31536000; includeSubdomains; preload" always;
    add_header Pragma "no-cache";

    #only secure cookies are here
    proxy_cookie_path   /                    "/; HTTPOnly; Secure";

    # use the below proxy_cookie_path to allow in-secure cookies, 
    # only useful for http in test environment
    # proxy_cookie_path   /                    "/; HTTPOnly";

    #ignore insecure headers by proxy
    proxy_ignore_headers    X-Accel-Expires;
    proxy_ignore_headers    Expires;
    proxy_ignore_headers    Cache-Control;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8000;  # Your Enpass Hub is running on port 8000
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
  3. Reload nginx server: 
    # remove default nginx conf
sudo rm /etc/nginx/sites-enabled/default
 
# Enable the Nginx configuration
sudo ln -s /etc/nginx/sites-available/enpass-hub /etc/nginx/sites-enabled/

# Test Nginx configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

 

Step 8: Check your setup

  1. Visit the URL you've created for your Enpass Hub (e.g., https://your-domain.com, as above) to confirm it's live.
    Sever is up message
  2. Enter a test email address, and click Send Test Email to confirm your email configuration is functioning in your seltup correctly.
  3. Enter a test email address, enable the Use Redis option, and click Send Test Email to confirm Redis is functioning correctly in your setup.

NOTE: This email-testing page will only be accessible until the first Enpass Hub Administrator has logged in, as described on the next page of this guide, Creating a Server Administrator for your Enpass Hub.

 

Before going to production, consider the following measures

Configure SSL

To ensure a secure connection, Enpass Hub needs to be available over HTTPS to communicate with the Enpass app. The guide uses an example to use Let's Encrypt certificate. You may already have your own long duration certificate from a different provider. You can also enable SSL certificate pinning during a later integration stage, which enhances the security of connection between the Enpass Hub and users’ Enpass apps by ensuring the apps communicates only with the server that matches the pinned certificate.

Updates

Make sure to regularly check for updates to the Enpass Hub Docker image. If there are updates, pull the new image and redeploy your Docker Compose setup to ensure your deployment is always up-to-date.

Database

Regular backups of your PostgreSQL database are critical for disaster recovery. For better control and data persistence, it's advisable to host your PostgreSQL database on a separate machine, outside of Docker Compose. Also consider encrypting your database to add an extra layer of security to your sensitive data.

 

Next Steps

Now that you have your Enpass Hub server ready for integration, here are the next steps: