Synaccess Cloud Installation & Setup

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 Cloud `.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.

Connection String

Syn Cloud 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 Syn Cloud .env file.

3. Edit Your Configuration (`.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:
```
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 Syn Cloud

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

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 Cloud 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 Syn Cloud:
```
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
Copy/Paste into Synaccess Cloud:
- Log into the Syn Cloud 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
```
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.

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).
Obtain the New .deb
- Download or copy the newer .deb onto your server.
Install / Upgrade
```
sudo dpkg -i synaccess-cloud_<new_version>_amd64.deb
```
- dpkg stops the old service, unpacks the new files, then restarts syn-cloud.
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.

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.