Skip to content

Self-Hosting Server

SocketXP IoT Management Platform server can be self-hosted in your data center or private/public cloud as a Virtual Machine(VM) instance.

The server is called SocketXP Gateway(socketxp-gtwy).

Download and Install

Download and install the SocketXP Gateway binary package for your Linux distribution as shown below:

Redhat/Centos/Fedora

curl -O https://portal.socketxp.com/download/socketxp-gtwy/socketxp-gtwy-2.1.2-1.x86_64.rpm
sudo yum install ./socketxp-gtwy-2.1.2-1.x86_64.rpm

Debian/Ubuntu

curl -O https://portal.socketxp.com/download/socketxp-gtwy/socketxp-gtwy_2.1.2-1_amd64.deb
sudo apt install ./socketxp-gtwy_2.1.2-1_amd64.deb

Note

After installation, socketxp-gtwy server will be running in the background as a Linux systemd service. The systemd service configuration file can be found at: /etc/systemd/system/socketxp-gtwy.service. The log file can be found under /var/lib/socketxp-gtwy/log/

Server Configuration

Create a configuration file named config.json under the folder /var/lib/socketxp-gtwy/ with the following configurations:

{
    "gateway_domain":"gateway.socketxp.example.com",
    "gateway_port":9443,
    "email": "[email protected]",
    "oidc_providers": [
            {
                "name": "microsoft",
                "client_id": "xxxxxxxxxx",
                "client_secret": "xxxxxxxxxxx",
            }
    ],
    "debug_level": "debug"
}
Register SocketXP Gateway as an OIDC client app with your OIDC SSO provider, say microsoft or google. How to do this is specific to your OIDC SSO provider and outside the scope of this documentation.

Use https://your-socketxp-portal-domain-name/api/logincallback as the OIDC client app's login callback API.

For this example, we'll register https://portal.socketxp.example.com/api/logincallback as the login callback API with the OIDC provider - Microsoft 365 or Google G-Suite.

Replace the client_id and client_secret in the above config file with the OIDC client app credentials provided by your OIDC SSO provider for the app.

Server SSL Certificate and Key

Register your server's wildcard domain name (*.socketxp.example.com) with Let'sEncrypt or any SSL certificate authority(CA) and get an SSL certificate/key pair for your server's wildcard domain name (*.socketxp.example.com).

Store the server's certificate chain file and the private key file as server.crt and server.key under the /var/lib/socketxp-gtwy folder.

License File

We offer a 30-day free trial license for our Enterprise Version software.

To create an Enterprise Free Trial License, login to the SocketXP Cloud Gateway in the US region at: https://portal.socketxp.com/ using your email ID.

Go to the License tab, click the "Start Free Trial" button. Fill in your organization details and requirements in the form and click the "Create Free Trial License" button. An new Free Trial License will be created.

Click the "Download License File" button to download the license file. Copy the license.pem file to /var/lib/socketxp-gtwy folder in your self-hosted VM server.

Database

By default, the server will create and use an SQLite DB file in the /var/lib/socketxp-gtwy directory to store information about the devices. This DB is good enough for trial and testing.

For production, you should use PostgreSQL DB. Here is a sample configuration for connecting the SocketXP Gateway server to a PostgreSQL DB. You should add the below DB configuration to the config.json file.

{
    ...
    ...

    "database": {
            "driver": "postgres",
            "hostname":"psqldb.example.com",
            "port":"5432",
            "user":"your-user",
            "password":"your-password",
            "db_name":"socketxp_db",
            "ssl_mode":"enable"
    },

    ...
    ...
}

Please update the values in the the above config file according to your DB settings.

Restart the Server

After you save the configuration file, restart the socketxp-gtwy server to pickup the above configuration changes, using the command shown below:

systemctl restart socketxp-gtwy

Access the Web Portal

Access the server's web portal by pointing your browser to https://portal.socketxp.example.com. Login using your SSO credentials as a primary admin user (Eg: [email protected]).

After you login to the web portal, you can provide your team members access to the server, by adding their email IDs in the MyTeam page under the Settings.

Your server is now ready to accept any device registration requests.

Accessing the APIs

Your SocketXP Gateway server's APIs can be accessed using the following subdomain URL:

https://api.socketxp.example.com

The API endpoints are same as the ones documented in the API Reference Guide.

For example, to list the devices in your account:

curl https://api.socketxp.example.com/v1/devices/:page_num/:rows_per_page \
  -X GET \
  -H "Authorization: Bearer <your-auth-token-goes-here>"

Accessing the Log file

Log files can be found at /var/lib/socketxp-gtwy/log/. Set the debug_level flag in the config.json file to one of: "error", "debug", "info". The flag when set to "error" will log less verbose output such as only errors. The "debug" option will print more verbose output such as debugs and errors. The "info" option will print the most verbose output such as info, debugs and errors.

Any Questions?

Please write to [email protected], if you have any questions.