Guides
Home

Self Hosted Central Management Portal (Debian)

Suggest Edits

Summary

This guide walks you through the installation, configuration, and setup of the Synaccess Self-Hosted Central Management Portal on an Ubuntu 20.04 LTS (or compatible Debian-based) server. It covers:

  • System Requirements

    • OS: Ubuntu 20.04 LTS
    • Hardware: Minimum 1 vCPU, 2GB RAM
    • Database: PostgreSQL v14.11 or higher
    • Networking: Open ports (80/443 recommended) and ensure device connectivity

  • Installation

    • Install the .deb package (sets up webserver and syn-cloud systemd service on port 3000)
    • Configure database and environment variables in the .env file

  • Database Setup

    • Use an existing PostgreSQL instance or deploy one locally, via Docker, or on a managed host
    • Create a database, user, and connection string

  • Configuration

    • Edit .env to set database credentials, ports, and optional features (TLS, SMTP)
    • Restart the service to apply changes

  • Web App Access

    • Open the web interface at http://<server-ip>:3000
    • Complete initial setup (migrations) and create a super admin user

  • Additional Features

    • Optionally configure SMTP for emails
    • Enable TLS for secure HTTPS traffic
    • Manage PDUs and users via the web UI

  • Maintenance

    • Update by replacing the .deb file and restarting the service
    • Monitor logs with journalctl
    • Manage the service with systemctl

With these steps, you’ll have a secure and fully operational Synaccess Central Management Portal instance, ready to manage your PDUs.

System Requirements

  • Operating System: Ubuntu 20.04 LTS (Debian-based distros also supported)
  • Hardware: At least 1 vCPU / 2GB RAM (supports up to 1000 devices)
  • Database: PostgreSQL v14.11 (or compatible)
  • Networking:
    • Application Ports: 80/443 (recommended), or a custom port for HTTP/HTTPS
    • TLS: Strongly recommended to secure traffic (HTTPS + WSS). Configurable in .env or web UI.
    • Device Connectivity: Your Synaccess PDUs must be able to reach this webserver over the designated ports (HTTP/HTTPS).
    • IP Whitelisting: If using a firewall, ensure inbound rules allow traffic from your PDUs to the webserver.
  • SMTP (Optional but recommended): For password reset emails and notifications.

1. Install the Synaccess Central Management Portal .deb Package

  1. Download or copy the synaccess-cloud_<version>_amd64.deb file to your Ubuntu/Debian server.
  2. Install it: 
    sudo dpkg -i synaccess-cloud_<version>_amd64.deb

    Note: Replace <version> with the actual version number (e.g., 1.2.3).

What this does:

  • Places the webserver executable in /opt/synaccess-cloud/syn-cloud
  • Installs a systemd service named syn-cloud
  • Automatically starts the service on port 3000 at http://localhost:3000

You should see it active (running). Logs might show DB connection errors if you haven’t set .env yet—this is normal initially.

2. Prepare PostgreSQL 14.11

If you already have PostgreSQL 14.11+ running—locally or on another server—skip this step. Otherwise, provide your own instance (e.g., via Docker, on a separate VM, or managed hosting).

Creating a Database & User

Wherever you run PostgreSQL, you’ll need a database and user with full privileges. For example, if you can access psql:

CREATE DATABASE syn1;
CREATE USER synuser WITH ENCRYPTED PASSWORD 'synpassword';
GRANT ALL PRIVILEGES ON DATABASE syn1 TO synuser;

Adjust the database name (syn1), username (synuser), and password (synpassword) as desired.

Install UUID-OSSP extension

UUID-OSSP extension is required.

sudo -u postgres psql -d syn1 -c "CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";"

Connection String

Synaccess Central Management Portal requires a connection string in the format:

postgresql://<username>:<password>@<host>:<port>/<dbname>

For example:

postgresql://synuser:synpassword@localhost:5432/syn1
  • username: synuser
  • password: synpassword
  • host: IP or hostname where PostgreSQL is running (e.g., localhost or db if Docker-based)
  • port: Typically 5432
  • dbname: syn1

Make sure you have this database connection string ready, as you’ll put it into your .env file.

3. Edit Your Configuration (.env.example)

  1. Navigate to /opt/synaccess-cloud: 
    cd /opt/synaccess-cloud
  2. Duplicate .env.example to .env: 
    cp .env.example .env
  3. Open .env: 
    nano .env
  4. Set your database connection string: 
    DB_CONNECTION_STRING="postgresql://synuser:synpassword:5432/syn1"
    Adjust synuser, synpassword, localhost, and 5432 as needed.

Optional Environment Variables

  • HOST: The IP your server binds to (e.g., 0.0.0.0 or 127.0.0.1).
  • PORT: The port for HTTP/HTTPS (default 3000).
  • TLS_CERT & TLS_KEY: If you want the server to run in HTTPS mode directly from Node.
  • CONNECTION_SECURITY: e.g., tls to enforce HTTPS.
  • SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD: For email notifications.

These network settings are also configurable in the web UI. Configurations set in the .env file will override configurations in the web UI.

4. Restart Synaccess Central Management Portal

After editing .env or making any changes to your deployment settings (such as port, TLS keys, etc.):

sudo systemctl restart syn-cloud

Your changes take effect after the service restarts.

5. Access the Web App

  • Open a browser (on the server or a remote machine) at: 
    http://<server-ip>:3000
    (If on the same server, http://localhost:3000.)
  • The web interface will guide you through initial setup, including migrations and creating a super admin user.
  • Super Admin: Manages all users, deployment settings, SMTP configuration, etc. You can also appoint additional admins later.

When editing webserver settings (e.g., port, TLS certs), you must restart the service for changes to take effect

Note: The system automatically runs DB migrations in the background. If the DB is reachable and credentials are correct, you won’t need a separate wizard for migrations.

6. Next Steps & Common Commands

  1. Finish Configuration:

  2. Service Management:

    # Stop the service
sudo systemctl stop syn-cloud

# Start the service
sudo systemctl start syn-cloud

# Follow real-time logs
sudo journalctl -u syn-cloud -f

Managing the Super Admin & Deployment Settings

During initial setup, you’ll create a super admin user responsible for:

  • Adding/managing additional users
  • Adjusting deployment settings (e.g., changing the webserver port, updating SSL certs, SMTP configuration, etc.)

Important: After any deployment setting change (port, SSL cert, etc.), you must:

sudo systemctl restart syn-cloud

to apply the changes.

Summary

  1. Install the .deb and configure PostgreSQL.
  2. Edit .env, then restart to activate settings.
  3. Access the web app at http://<server-ip>:3000 to complete initial setup.
  4. (Optional) Set up Docker-based PostgreSQL, SSL/TLS certs, and SMTP for password resets.
  5. Always restart after changing critical deployment settings.

With these steps, you have a fully functional Synaccess Central Management Portal instance that you can manage, secure with HTTPS, and connect to your Synaccess PDUs. Additional customization (e.g., backups, high availability, advanced firewall rules) can be added as your deployment grows.

Optional: Set Up PostgreSQL with Docker Compose

If you prefer Docker for your database, here’s a minimal docker-compose.yml:

version: "3.8"
services:
  db:
    image: postgres:14.11-alpine
    container_name: syn-cloud-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=synuser
      - POSTGRES_PASSWORD=synpassword
      - POSTGRES_DB=syn1
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  pgdata:

Usage

  1. Create a file named docker-compose.yml with the above contents.
  2. Run: 
    docker-compose up -d
  3. Confirm the container is running: 
    docker ps
  4. In your .env, set: 
    DB_CONNECTION_STRING=postgresql://synuser:synpassword@localhost:5432/syn1
  5. Restart Synaccess Central Management Portal: 
    sudo systemctl restart syn-cloud

Optional: Set Up SSL Certs for Public Server (Ubuntu 20.04)

  1. Install Certbot:

    sudo apt update
sudo apt install certbot

  2. Obtain Certificates (using standalone mode):

    sudo certbot certonly --standalone -d your-domain.com

    Certbot places your certificates here (by default):

    • Certificate: /etc/letsencrypt/live/your-domain.com/fullchain.pem
    • Private Key: /etc/letsencrypt/live/your-domain.com/privkey.pem

  3. Copy/Paste into Synaccess Central Management Portal:

    • Log into the Synaccess Central Management Portal web interface as super admin.
    • Paste the certificate/key into the SSL/TLS settings (or environment variables if your .env approach uses TLS_CERT and TLS_KEY).
    • Restart for changes to take effect: 
      sudo systemctl restart syn-cloud

  4. Optionally, forward port 80 to 443 or set up systemd to do so if you want forced HTTPS.

SSL / HTTPS

There are two main ways to enable HTTPS:

  1. Use .env to embed your cert and key:

    TLS_CERT="(contents of your fullchain.pem)"
TLS_KEY="(contents of your privkey.pem)"
CONNECTION_SECURITY="tls"
PORT="443"

    Then:

    sudo systemctl restart syn-cloud

    Now the server listens on HTTPS (port 443).

  2. Use a Reverse Proxy (e.g., Nginx or Caddy):

    • Have Nginx handle SSL termination, forward traffic to http://localhost:3000.

Let’s Encrypt (Certbot) example:

sudo apt-get update
sudo apt-get install certbot
sudo certbot certonly --standalone -d yourdomain.com
# Certs located at /etc/letsencrypt/live/yourdomain.com/
# Combine them into TLS_CERT/TLS_KEY or serve them via Nginx.

Below is a concise “Version Upgrades” section for your documentation:

Version Upgrades

When a new synaccess-cloud_<version>_amd64.deb is released, follow these steps to upgrade:

  1. Optional Backup

    • If desired, back up your database (e.g., using pg_dump if Docker-based PostgreSQL).

  2. Obtain the New .deb

    • Download or copy the newer .deb onto your server.

  3. Install / Upgrade 

    sudo dpkg -i synaccess-cloud_<new_version>_amd64.deb
    • dpkg stops the old service, unpacks the new files, then restarts syn-cloud.

  4. Check Logs 

    sudo journalctl -u syn-cloud -f
    • Verify the upgraded service starts correctly and connects to your database.

  5. Validate

    • Access the web UI (e.g., http://<server-ip>:3000) to confirm everything is functioning and you’re on the latest version.

Note: Your existing .env and database remain intact, so configuration persists. If .env contains port/TLS settings, they still override any UI-based changes after the upgrade.

Updated 14 days ago