Deployment requirements
What you need before installing Workforce Intelligence: a box, open ports, a token for the image registry, and a public address.
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.shinstalls Docker for you when it is missing, and the CloudFormation template installs Docker and the Compose plugin during first boot. - Has
sudoaccess for the account you install with, andopensslavailable (used to generate secrets). - Can reach the internet to pull container images from the image registry (
ghcr.ioby 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:
- A GitHub account with read access to the
wi-serverandwi-webpackages. 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. - A classic personal access token for that account with the
read:packagesscope 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.