Self Hosted Central Management Portal (Debian)
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 andsyn-cloud
systemd service on port 3000) - Configure database and environment variables in the
.env
file
- Install the
-
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
- Edit
-
Web App Access
- Open the web interface at
http://<server-ip>:3000
- Complete initial setup (migrations) and create a super admin user
- Open the web interface at
-
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
- Update by replacing the
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
.deb
Package- Download or copy the
synaccess-cloud_<version>_amd64.deb
file to your Ubuntu/Debian server. - 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
ordb
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
)
.env.example
)- Navigate to
/opt/synaccess-cloud
:cd /opt/synaccess-cloud
- Duplicate
.env.example
to.env
:cp .env.example .env
- Open
.env
:nano .env
- Set your database connection string:
Adjust
DB_CONNECTION_STRING="postgresql://synuser:synpassword:5432/syn1"
synuser
,synpassword
,localhost
, and5432
as needed.
Optional Environment Variables
- HOST: The IP your server binds to (e.g.,
0.0.0.0
or127.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:
(If on the same server,http://<server-ip>:3000
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
-
Finish Configuration:
- Set up Synaccess PDUs (point them to this server).
- Optionally configure SMTP for password reset emails (see Optional: Configure SMTP).
- Configure SSL if needed (see Optional: SSL Setup).
-
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
- Install the .deb and configure PostgreSQL.
- Edit
.env
, then restart to activate settings. - Access the web app at
http://<server-ip>:3000
to complete initial setup. - (Optional) Set up Docker-based PostgreSQL, SSL/TLS certs, and SMTP for password resets.
- 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
- Create a file named
docker-compose.yml
with the above contents. - Run:
docker-compose up -d
- Confirm the container is running:
docker ps
- In your
.env
, set:DB_CONNECTION_STRING=postgresql://synuser:synpassword@localhost:5432/syn1
- Restart Synaccess Central Management Portal:
sudo systemctl restart syn-cloud
Optional: Set Up SSL Certs for Public Server (Ubuntu 20.04)
-
Install Certbot:
sudo apt update sudo apt install certbot
-
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
- Certificate:
-
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 usesTLS_CERT
andTLS_KEY
). - Restart for changes to take effect:
sudo systemctl restart syn-cloud
-
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:
-
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).
-
Use a Reverse Proxy (e.g., Nginx or Caddy):
- Have Nginx handle SSL termination, forward traffic to
http://localhost:3000
.
- Have Nginx handle SSL termination, forward traffic to
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:
-
Optional Backup
- If desired, back up your database (e.g., using
pg_dump
if Docker-based PostgreSQL).
- If desired, back up your database (e.g., using
-
Obtain the New
.deb
- Download or copy the newer
.deb
onto your server.
- Download or copy the newer
-
Install / Upgrade
sudo dpkg -i synaccess-cloud_<new_version>_amd64.deb
- dpkg stops the old service, unpacks the new files, then restarts
syn-cloud
.
- dpkg stops the old service, unpacks the new files, then restarts
-
Check Logs
sudo journalctl -u syn-cloud -f
- Verify the upgraded service starts correctly and connects to your database.
-
Validate
- Access the web UI (e.g.,
http://<server-ip>:3000
) to confirm everything is functioning and you’re on the latest version.
- Access the web UI (e.g.,
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