Enpass Hub on a Standalone Linux Server

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:

• Example docker-compose.yaml

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.

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.

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.

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.