Deploy Unusual Suite On-Premises

You can run your own Unusual Suite server so that all your data stays on your own infrastructure. The on-premises server still connects to the Unusual Suite licence server for compliance checks and product support, but none of your data is sent to Unusual Suite.

Prerequisites

  • An ARM64 Linux server with at least 2 GB RAM and 1 GB of available disk space.
  • The server must be reachable via a URL or external IP address.
  • Port 80 must be available for a non-SSL setup. Native SSL is not supported by the on-premises server itself — provide SSL termination via a reverse proxy.
  • MariaDB 11.8.2 or later must be installed with sufficient disk space for your data. You'll need these database credentials ready:
    • server — IP or domain of the MariaDB instance (e.g. localhost)
    • database — name of the database that will hold Unusual Suite data (created automatically during setup if it doesn't exist yet)
    • user — database username
    • password — database password
  • A valid email address for the superuser/administrator. This address is permanent and cannot be changed after setup.
  • An Unusual Suite subscription. Your internal key — which authenticates the on-premises server with the Unusual Suite licence server — is available at 'My Account' ⟶ 'About'. You must be signed up to retrieve it.
  • If you want to use external services such as AI (for example in Power-Chat), you need valid accounts and API keys for those services. See the Configuration section below for the full list.

Recommended MariaDB Configuration

Apply these settings to your MariaDB instance before installation:

collation_server: utf8mb4_uca1400_ai_ci or utf8mb4_unicode_ci
character_set_client: utf8mb4
character_set_connection: utf8mb4
character_set_database: utf8mb4
character_set_results: utf8mb4
character_set_server: utf8mb4
log_bin_trust_function_creators: 1
max_allowed_packet: 67108864

Install the Unusual Suite On-Premises Server

The commands below install the Unusual Suite server on an Ubuntu server where the user ubuntu already exists. The server is installed in that user's home directory. Adapt the commands for your own setup. Run all commands with root privileges.

# install unzip if not installed already
apt update
apt install unzip

# create assets and trace subdirectory
mkdir -p /home/ubuntu/assets /home/ubuntu/trace
chmod 755 /home/ubuntu/assets /home/ubuntu/trace
chown -R ubuntu:ubuntu /home/ubuntu/assets /home/ubuntu/trace

# get and unzip Unusual Suite server binary
# assign elevated privileges so the Unusual Suite server can listen on port 443 (SSL) or 80 (non-SSL)
rm -f /home/ubuntu/Unusual.Server
wget --no-cache -P /home/ubuntu/assets https://ds-01.unusual-suite.com/assets/Unusual.Server.zip
unzip -o /home/ubuntu/assets/Unusual.Server.zip Unusual.Server -d /home/ubuntu
chmod 555 /home/ubuntu/Unusual.Server
rm -f /home/ubuntu/assets/Unusual.Server.zip
setcap 'cap_net_bind_service=+ep' /home/ubuntu/Unusual.Server

# get webassembly binary
rm -f /home/ubuntu/assets/Unusual.WebAssembly.zip
wget --no-cache -P /home/ubuntu/assets https://ds-01.unusual-suite.com/assets/Unusual.WebAssembly.zip
chown ubuntu:ubuntu /home/ubuntu/assets/Unusual.WebAssembly.zip
chmod 600 /home/ubuntu/assets/Unusual.WebAssembly.zip

# create config file
# - replace 'user', 'password' etc. in 'ConnectionString'
# - set the actual domain or IP in 'HostName'
# - set your immutable license email in 'UnusualLicenseEmail'
cat <<EOF > /home/ubuntu/Unusual.xml
<?xml version="1.0" encoding="utf-8"?>
<Unusual>
 <ConnectionString>server=localhost;database=unusual;user=unusual;password=unusual</ConnectionString>
 <HostName>mydomain.com</HostName>
 <InternalKey>your-internal-key</InternalKey>
 <UnusualLicenseEmail>myemail@mydomain.com</UnusualLicenseEmail>
</Unusual>
EOF
chown ubuntu:ubuntu /home/ubuntu/Unusual.xml
chmod 600 /home/ubuntu/Unusual.xml

# create Unusual Suite service
cat <<EOF > /etc/systemd/system/unusual.service
[Unit]
Description=Unusual Server
[Service]
ExecStart=/home/ubuntu/Unusual.Server --installPath=/home/ubuntu
Restart=always
RestartSec=60
StandardError=file:/home/ubuntu/trace/stderr.txt
StandardOutput=file:/home/ubuntu/trace/stdout.txt
SyslogIdentifier=unusual
User=ubuntu
WorkingDirectory=/home/ubuntu/
[Install]
WantedBy=multi-user.target
EOF

# enable and start the Unusual Suite service
systemctl enable unusual.service
service unusual start

Verify the Installation

Go to the /home/ubuntu/trace directory and open the most recent trace file. A line containing Server.Server.Main.Run confirms that the Unusual Suite server is up and running.

Log In for the First Time

Once the server is running, log in using these credentials:

  • URL: http://<mydomain.com>/login (replace the domain with your actual domain)
  • User: the email address you provided during setup
  • Password: the database password from your connection string

The initial login password defaults to the database password in your connection string. Change your login password after first login. The database password is not affected when you change your login password.

Configure a Default SMTP Email Account

The Unusual Suite server requires a default SMTP email account to send notification emails. If no account is configured, the following line appears in the trace files:

Server.Server.SMTP: No SMTP default account configured

Make sure your server's DNS records include the correct DMARC and DKIM entries so that outgoing emails are not rejected.

Update the On-Premises Server

To update, you need to replace both the server binary and the WebAssembly archive. Run the following commands with root privileges:

# get and unzip Unusual Suite server binary
# assign elevated privileges so the Unusual Suite server can listen on port 443 (SSL) or 80 (non-SSL)
rm -f /home/ubuntu/Unusual.Server
wget --no-cache -P /home/ubuntu/assets https://ds-01.unusual-suite.com/assets/Unusual.Server.zip
unzip -o /home/ubuntu/assets/Unusual.Server.zip Unusual.Server -d /home/ubuntu
chmod 555 /home/ubuntu/Unusual.Server
rm -f /home/ubuntu/assets/Unusual.Server.zip
setcap 'cap_net_bind_service=+ep' /home/ubuntu/Unusual.Server

# get webassembly binary
rm -f /home/ubuntu/assets/Unusual.WebAssembly.zip
wget --no-cache -P /home/ubuntu/assets https://ds-01.unusual-suite.com/assets/Unusual.WebAssembly.zip
chown ubuntu:ubuntu /home/ubuntu/assets/Unusual.WebAssembly.zip
chmod 600 /home/ubuntu/assets/Unusual.WebAssembly.zip

# stop and re-start the service
service unusual stop
service unusual start

Configuration Reference

All configuration is controlled by the file /home/ubuntu/Unusual.xml.

Mandatory properties

  • ConnectionString — the database connection string, containing:
    • server — domain or IP of the database server (e.g. localhost)
    • database — name of the database
    • user — username to connect to the database
    • password — password to connect to the database
  • InternalKey — the internal key from the prerequisites section above
  • HostName — IP or domain of the on-premises server
  • LicenseEmail — the immutable licence email from the prerequisites section above

Optional properties

  • DeepLApiKey — API key for DeepL translation services
  • FireCrawlApiKey — API key for FireCrawl to crawl and scrape websites
  • GenderizeApiKey — API key for Genderize IO to detect gender from contact names
  • MistralAIApiKey — API key for Mistral AI services
  • OcrSpaceApiKey — API key for OCR Space to extract text from PDF or image documents
  • OpenAIApiKey — API key for OpenAI services
  • UseSsl — set to 'True' (default) if the server is accessible via SSL; set to 'False' if you're not using SSL

System-managed properties — do not edit

  • AesKey and AesIV — encryption keys used to protect stored credentials such as passwords. These are set automatically by Unusual Suite. Do not delete or modify these values, or you will lose access to any credentials stored in the database.