Deployment requirements

What you need before installing Workforce Intelligence: a box, open ports, a token for the image registry, and a public address.

For: Administrators installing or hosting Workforce Intelligence · Last updated

Workforce Intelligence runs as a set of Docker containers on a single Linux box that you control. This article lists what must be in place before you start either install path (AWS CloudFormation or on-premises).

The box#

You need a Linux machine, virtual or physical, that:

  • Runs Docker with the Docker Compose plugin. install.sh installs Docker for you when it is missing, and the CloudFormation template installs Docker and the Compose plugin during first boot.
  • Has sudo access for the account you install with, and openssl available (used to generate secrets).
  • Can reach the internet to pull container images from the image registry (ghcr.io by default) and, if you use a domain, to complete certificate issuance.
  • Has enough room for Postgres, the application, the web server, the Dokku container, and the per-company Coworker workbench containers that run on the same Docker daemon. The CloudFormation template defaults to a t3.large (2 vCPU, 8 GiB) with a 40 GiB root volume as a starting point.

Ports#

Port Used for Notes
80 Web app over HTTP Also used for the certificate challenge when you configure a domain.
443 Web app over HTTPS Used when you set WI_DOMAIN.
2222 (default) Dokku SSH, where Builders push code for deployed Apps Change it with WI_DOKKU_SSH_PORT.

Open these to wherever your users and Builders connect from. You can change the published HTTP and HTTPS ports with WI_HTTP_PORT and WI_HTTPS_PORT (see Configuration reference).

The Dokku container publishes its SSH port on the host, port 2222 by default, so it never collides with the box's own SSH server on 22. Open that port to your Builders.

The CloudFormation template opens ports 80 and 443 (to HttpCidr and HttpsCidr), port 2222 (to DokkuSshCidr, default 0.0.0.0/0), and port 22 only when you set SshCidr. If you change WI_DOKKU_SSH_PORT, add an inbound rule for the new port to the stack's security group yourself.

Outbound access to Workforce Intelligence#

The box needs outbound HTTPS to the address in WI_CENTRAL_URL. The application uses it for one small call that connects the deployment's ID (a public key, an ID and your company name, nothing else), made in the background whether or not sharing is on, and for bug reports only while an administrator has turned on Share bug reports with Workforce Intelligence. Blocking that connection is safe: the ID shows Connecting…, bug reports stay in your deployment and the product works as usual. See Data sharing with Workforce Intelligence.

A token for the image registry#

The application images are private packages: wi-server and wi-web. By default they are served from the GitHub Container Registry (ghcr.io) under the image owner radialventures. If Workforce Intelligence gives you a different registry host, set WI_IMAGE_REGISTRY to it, set WI_IMAGE_OWNER to the namespace Workforce Intelligence gives you (wi on harbor.getwi.com) and use the credentials Workforce Intelligence gives you for that host.

For ghcr.io you need:

  1. A GitHub account with read access to the wi-server and wi-web packages. Confirm this on the organization's packages page before you start. Membership in a GitHub organization does not by itself grant read access to every private package.
  2. A classic personal access token for that account with the read:packages scope and nothing else. Fine-grained personal access tokens do not work with GHCR. This is a limitation of the GitHub registry, not of Workforce Intelligence.

You provide the username and token once, to install.sh, as REGISTRY_USER and REGISTRY_TOKEN (GHCR_USER and GHCR_TOKEN work as aliases). Docker stores the login on the host, and later pulls and in-app updates reuse it. See Registry credentials for updates for what to do when the token expires.

An address for the app#

Decide how people will reach the box before you install:

  • A domain name that resolves to the box. With it, Caddy obtains and renews a real certificate and serves HTTPS. See Domains and HTTPS.
  • A hostname or IP address with plain HTTP. The app is served, but in production the session cookie is marked secure, so browsers do not keep a sign-in made over plain HTTP. Use a domain with HTTPS for anything people will sign in to.

The domain you choose becomes WI_DOMAIN (for example wi.example.com), and the web origin https://wi.example.com is derived from it. With no domain, set WI_ALLOWED_ORIGIN to the http:// address instead.

Outbound access for chat apps#

If you connect Coworkers to Slack or Microsoft Teams (see Connect Slack and Connect Microsoft Teams), the box needs outbound HTTPS (port 443) to the chat service. Nothing is opened inbound for this by the install, and an unrestricted outbound path needs no change.

Chat app Outbound HTTPS the box needs Inbound
Slack, with Slack sends events to us slack.com and its subdomains (replies, file downloads and uploads) Slack must reach your API address over https://.
Slack, with We connect to Slack (Socket Mode) slack.com and its subdomains, including the WebSocket address Slack hands out None.
Microsoft Teams, directly login.microsoftonline.com, login.botframework.com and smba.trafficmanager.net, plus the address Microsoft gives for files people attach, and graph.microsoft.com when Allow in channels is on (the Coworker reads the messages around a mention) Microsoft must reach your API address over https://.
Microsoft Teams, We connect to Microsoft directly (Socket mode) login.microsoftonline.com, smba.trafficmanager.net, *.botapi.skype.com (the regional connection setup) and the connection address Microsoft returns, plus graph.microsoft.com when Allow in channels is on None.

Where the box must be reachable from#

If you use a domain with automatic HTTPS, ports 80 and 443 must be reachable from the public internet so the certificate authority can verify the domain. A box behind NAT, such as one in a private subnet routed through a NAT gateway, cannot complete that verification.