Setting up on an Amazon EC2 instance

This guide walks you through setting up an EC2 Linux server with the udServer ThinApp and PostgreSQL database on the same virtual machine.

These steps assume some familiarity with Linux and having already set up an instance and having the SSH key handy.

The final version of this will be a server that runs on HTTP, it can be configured to serve HTTPS as well but that is outside of the scope of this guide.

On AWS we recommend putting the server behind another service (e.g. AWS ELB) to serve HTTPS using domains in Route 53 more easily.

Setup and start the postgres server

SSH into your instance and run the following commands to set up the PostgreSQL server.

sudo yum install postgresql16-server
sudo yum install postgresql16-contrib
sudo /usr/bin/postgresql-setup --initdb
sudo systemctl start postgresql

Create the database

You should set your own password here replacing new_password which you will need for the config file later.

sudo -u postgres psql
CREATE DATABASE udServer;
ALTER USER postgres PASSWORD 'new_password';
\q

sudo nano /var/lib/pgsql/data/pg_hba.conf

Towards the end of the file you need to change ident to md5 for IPv4 local connections.

Afterwards, restart the postgresql service to apply the changes.

sudo systemctl start postgresql

By default postgresql isn't setup to restart when the VM restarts either which can be fixed with

sudo systemctl enable postgresql

Upload the package using scp and your EC2 SSH key, we recommend unpacking the udServer ThinApp into a folder called webserver. This will be mirrored on the server to ~/webserver as a staging area.

scp -i "SSHKey.pem" -r ../builds/webserver ec2-user@ec2-12-34-56-78.compute-1.amazonaws.com:~

SSH in and setup the server

sudo yum install libpq
cd webserver/
chmod +x ./udServer

Setup Licenses file

The easiest license setup is to copy the contents of the license that Nuclideon provided and paste them into /var/opt/udserver/licenses.json.

Setup Config File

To start with, copy the below into /var/opt/udserver/config.json.

{
  "database": {
    "connections": 10,
    "dbname": "udserver",
    "host": "localhost",
    "username": "postgres",
    "password": "new_password",
    "port": 5432
  },
  "server": {
    "address": "0.0.0.0",
    "http": 80,
    "https": 443,
    "url": "<URL>"
  }
}

You will need to change:

The database password to match what you set when you set up the database.
The <URL> to match what the final user facing domain will be. e.g. https://udcloud.nuclideon.com this will be used by the OAuth redirect URL and if this isn't set correctly your users might not be able to login.

Testing

At this stage it's a good idea to make sure it all works by running the server in the current session.

cd ~/webserver
sudo ./udServer

Switch to use a systemd service

Running as a service means that the server will continue to operate with SSH disconnected.

The SOP for this is to put the server files into /opt/udserver.

Create the folder if it doesn't already exist with sudo mkdir /opt/udserver
Copy the files you uploaded with scp using sudo cp -r ~/webserver/* /opt/udserver/

You can now create the service file /etc/systemd/system/udServer.service with the following template.

[Unit]
Description=Nuclideon udServer
StartLimitInterval=200
StartLimitBurst=5

[Service]
WorkingDirectory=/opt/udserver
ExecStart=/opt/udserver/udServer
SyslogLevelPrefix=false
Type=idle
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target

After that's created you need to reload the services and start the server.

sudo systemctl daemon-reload
sudo systemctl enable udServer
sudo systemctl start udServer

If you want to connect to see what the server is doing this can be done using the standard service journal process.

journalctl -u udServer.service -n 10 -f

Support

If you get stuck during this process, feel free to contact us on it@nuclideon.com for support.