Skip to main content

Install Linksight with Docker Compose (supervised)

Prerequisites​

Before installation, make sure the following is ready:

  • One virtual machine
    • Minimum specifications: 4 (v)CPUs, 16 GB memory, 50 GB SSD storage
      info

      Optimal configuration depends on use-case and size of datasets. In general, more is better; the data station utilizes all CPU cores available during computation.

  • A user account on the Governance Hub (https://linksight.network) with the IT admin or Organization admin role.
    • No user account? Ask your organization administrator to invite you to the organization, or create a new organization after signing in.
  • (Optional) A TLS certificate to secure the Analysis Hub.
    • Using a TLS certificate is optional, however it is recommended to secure the connection between the user and the backend.
    • It is possible to automatically issue a certificate using Let's Encrypt. Review the page TLS to setup and enable automated certificate issuance.
    • TLS connections can also be established in other ways, e.g. by using a reverse proxy which terminates TLS.
caution

If there is a firewall enabled for the VM, please review the Connections & firewall rules page and apply the listed firewall rules to be able to connect to the services of Linksight.

Install Docker + Docker Compose​

Install Docker + Docker Compose on the virtual machine. For instructions, see:

info

The documentation, docker-compose.yaml and .env files are based on a minimum Docker version of 20.04.x, and docker-compose version 2.x.x. Older versions might work as well, but may result in unexpected behavior.

caution

By default the docker daemon always runs as the root user. If you don't want to preface the docker compose commands in this guide with sudo, you can create a Unix group called docker and assign users to it. See Linux post-installation steps for Docker Engine for additional information.

Set up working directory​

Create a working directory for your installation:

mkdir <workdir>
cd <workdir>

Configuration and Deployment​

  1. Download the Docker Compose file template for the supervisor, and put the files in the working directory.

    Alternatively, download the files using curl:

    curl -f -o docker-compose.yml https://setup.linksight.network/v3-supervisor/docker-compose.yml
    curl -f -o .env https://setup.linksight.network/v3-supervisor/.env.example

  2. Configure the following variables in the .env file:

    Required variables​

    Environment variableDescription
    FULLDATAPATHThe full (absolute) path to the directory which will store the persisted data. For example /path/to/workdir/data on Linux, or C:\path\to\workdir\data on Windows.
    ANALYSISHUB_FRONTEND_FQDNFully qualified domain name (FQDN) of the Analysis Hub. This will be used in the OIDC redirect URL if using an OIDC identity provider. E.g. https://my.domain-name.com or http://my.domain-name.com:8000. Make sure to configure ANALYSISHUB_PORT accordingly.
    DATASTATION_HOSTThe external public hostname/IP of the VM where other (external) data stations can reach the data station.

    Optional variables​

    Environment variableDescription
    ANALYSISHUB_FRONTEND_TLS_CERTFILE, ANALYSISHUB_FRONTEND_TLS_KEYFILESet to secure the connection to the Analysis Hub with TLS. Leaving these variables empty results in connections without TLS.

    The files should be put in the <workdir>/data/analysis folder, after creating it:
    mkdir <workdir>/data
    mkdir <workdir>/data/analysis

    The keys and certificates should then be transferred ownership to the user 65532:
    sudo chown 65532:65532 <workdir>/data/analysis/<key>.key
    sudo chown 65532:65532 <workdir>/data/analysis/<cert>.crt

    The ANALYSISHUB_FRONTEND_TLS_ variables can then be set to /data/<key>.key and /data/<cert>.crt (so without analysis in the path).
    ANALYSISHUB_AUTOCERT_ENABLEDEnable automatic certificate issuance from Let's Encrypt. Review page TLS for more info.
    ANALYSISHUB_AUTOCERT_HTTP01_ENABLEDEnable server for Let's Encrypt http-01 challenge responses on port 80. Enabled by default. Review page TLS for more info.
    ANALYSISHUB_AUTH_PROVIDERIdentity provider used for authentication to the Analysis Hub. The default value is linksight. Other options are localdb, microsoft, customoidc. See User Identity Management for more information on user identities and identity providers.
    ANALYSISHUB_AUTH_XXXDepending on the chosen identity provider, additional configuration might be required. Consult the User Identity Management page to learn more.
    ANALYSISHUB_PORTPort for the Analysis Hub frontend. Defaults to 8000.
    ANALYSISHUB_GRPC_PORTPort for the Analysis Hub backend gRPC server. Defaults to 8080.
    DATASTATION_ALTHOSTSAlternative hosts for the datastation, comma-separated. These will be used by internal components to route traffic internally.
    DATASTATION_HTTP_PORTPort for the data station mTLS HTTP server. Defaults to 8443. It should be externally accessible.
    DATASTATION_GRPC_PORTPort for the data station mTLS gRPC server. Defaults to 9090. It should be externally accessible.
    SUPERVISOR_USERUser for the supervisor container. Format is UID:GID. It needs read access to the Docker engine socket. Defaults to :.
    SUPERVISOR_DOCKER_SOCKETAbsolute path to the Docker engine socket. Defaults to /var/run/docker.sock.
note

In Supervised mode, the supervisor container must be run as a user with read access to the Docker socket. By default this is set to the user with UID=0, GID=0. This setting can be changed with the environment variable SUPERVISOR_USER.

Start components​

All components can be started by running:

docker compose up -d
info

Note that older versions of docker-compose require the command to be docker-compose instead of docker compose.

Check whether the frontend of the Analysis Hub is reachable (URL configured as ANALYSISHUB_FRONTEND_FQDN).

Follow the instructions on the page to complete the registration for the Analysis Hub and data station (accepting the registration tokens on the Linksight Governance Hub).

Check the logs to see whether all components have been registered successfully:

docker compose logs -f
info

The Linksight software is now up and running! Follow the instructions on the page Register nodes to register the nodes.

Next steps​

  • Register the nodes. Follow the instructions on the page Register nodes.