Self-hosted installation

Overview

These instructions will guide you through configuring and installing the Somewear Core service. The installation requires that both a Redis instance as well as a Postgresql instance with the PostGIS extension installed are already deployed, configured, and accessible from the Linux host(s) that will be running the Somewear Core service.

If you are running a highly available architecture with multiple Linux hosts running the Somewear Core service, the following installation steps will need to be repeated on each host.

Requirements

• 1 or more servers running Ubuntu or Debian Linux

  • 4 CPU cores

  • 16 GB RAM

  • 100 GB disk storage

• Postgres with PostGIS extension installed

• Redis

• Java 17

• Somewear Labs Pilot CLI tool

Architecture

Installation Steps

Run the installation script. This will setup the Pilot CLI tool and the pilot user which will be used to run the tool. The script will also initialize the necessary configuration files.

bash -c "$(curl -sSL https://get.somewear.app/install.sh)"

When the script gets to that part that states "Initializing pilot properties file...", this is an interactive wizard for create the configuration file for the Pilot CLI tool. You will be prompted fill in the values for the basic artifact credentials, API address of your installation, and app storage directory. We recommend that you accept the default value presented for the storage directory, but this can be overridden if desired. Below is an example of running through the setup wizard.

Initializing pilot properties file...
Creating new configuration file at ~/.config/somewear/pilot.properties...
Enter a value for each property
api-address (Web address for the api server. i.e. api.somewear.co): api.example.org
core-artifact-credentials (Basic credentials for the artifact repository): username:password
app-storage-directory (Directory for storing Somewear Core application data) [/opt/somewear]:

Configuration file created.

When you get to the step where you see "Initializing somewear.conf file...", this is another interactive wizard to create the configuration file for the Somewear Core service. You will be prompted to provide settings for connection to Postgres and Redis. For the device private key, use the key provided to you by the Somewear Labs team. The last prompt is to create an identity that will be the initial admin account for the service. Below is an example of running through the setup wizard.

Initializing somewear.conf file...
Creating new Somewear core configuration file at ~/.somewear/pilot/core/somewear.conf...
Enter a value for each property
POSTGRES_DB_HOST (Formatted as host:port): postgres:5432
POSTGRES_USER (): postgres
POSTGRES_PASSWORD (): myS3cr3t
REDIS_HOST (): redis
REDIS_PORT () [6379]:
WEB_APP_URL (Web address URL for the server. i.e. https://api.somewear.co): https://api.somewear.co
SW_FILE_STORAGE_PATH (Directory for storing Somewear Core application data) [/opt/somewear]:
SOMEWEAR_DEVICE_PRIVATE_KEY (): <REDACTED>
SOMEWEAR_IDENTITIES_TO_CREATE (Formatted as username:password:SystemOwner): sw-admin:myS3cr3t:SystemOwner

Configuration file created.

Use Pilot to download the latest version of the Somewear Core service JAR file

$ pilot pull

Run the Pilot prepare command which will perform the following steps.

• Creates a non-privileged service account user for the Somewear Core service to run as.

• Creates the lib and log directories in the somewear file storage path and updates ownership of these new directories.

$ pilot node prepare

Run the Pilot install command to perform the following steps.

• Generates a systemd unit file for running the Somewear Core service.

• Copies the Somewear Core service JAR and config file to the lib directory.

• Sets appropriate file ownership and permissions on the copied files.

$ pilot node install

Start the Somewear Core service and watch the startup logs.

$ pilot node launch && pilot node watch