Getting started¶
wis2box can be run on any Linux instance (bare metal or cloud hosted VM) with Python, Docker and Docker Compose installed. The recommended OS is Ubuntu 20.04 LTS.
Note
wis2box may work on other operating systems (for example AlmaLinux or Windows), but the officially supported OS is Ubuntu.
When choosing the environment for the wis2box, consider the following:
The wis2box instance should have suitable Internet connectivity, to download the required Docker images used in the wis2box stack
In order for the wis2box instance to function as a WIS2 Node, HTTP and MQTT ports on the instance need to be accessible over the public Internet
Ensure that the system providing input data can access the wis2box instance
Note
Before exposing the wis2box to the Internet, please review the ‘security considerations’ section in the Public services setup section.
Network requirements¶
The wis2box-software requires the following network ports to be available on the host system:
80/tcp (HTTP)
1883/tcp (MQTT)
3000/tcp (Grafana)
9000/tcp (MinIO)
9001/tcp (MinIO Console)
In order for the wis2box to be accessible from the Internet, the following ports on the host should be routed to a public IP address:
80/tcp (HTTP)
1883/tcp (MQTT)
It is recommended to use a reverse proxy (for example NGINX) to provide HTTPS access to the wis2box.
System requirements¶
System requirements depend on the amount of data ingested. We recommend minimum 2 vCPUs with 4GB Memory and 24GB of local storage.
For example, the following Amazon AWS EC2 instance types have been utilized as part of various wis2box demonstrations.
0 - 2000 observations per day: t3a.medium instance:
2 vCPUs, x86_64 architecture, 4GB Memory, up to 5 Gigabit network, 24GB attached storage (~35 USD per month for on-demand Linux based OS)
2000 - 10000 observations per day: t3a.large instance:
2 vCPUs, x86_64 architecture, 8GB Memory, up to 5 Gigabit network, 24GB attached storage (~70 USD per month for on-demand Linux based OS)
Software dependencies¶
The services in wis2box are provided through a stack of Docker containers, which are configured using Docker Compose.
wis2box requires the following prior to installation:
Requirement |
Version |
---|---|
Python |
3.8 or higher |
Docker Engine |
20.10.14 or higher |
Docker Compose |
2.0 or higher |
The following commands be used to setup the required software on Ubuntu (20.04 LTS, 22.04 LTS) systems:
Note
Execute the below commands one by one, and do not copy / paste the entire block
sudo mkdir -m 0755 -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor --yes -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
sudo echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get -y update
sudo apt-get install -y docker-ce docker-compose-plugin unzip python3-pip
sudo pip3 install pip --upgrade
sudo pip3 install pyopenssl --upgrade
sudo pip3 install requests==2.26.0 urllib3==1.26.0
The following commands can be used to inspect the available versions of Python, Docker and Docker Compose on your system:
docker version
docker compose version
python3 -V
The wis2box software should be run by system user that is part of the docker
group.
The following command can be used to add the current user to the docker
group:
sudo usermod -aG docker $USER
Switch to this user and check that you can run docker hello-world:
sudo su - $USER
docker run hello-world
You should see the following output:
Hello from Docker!
This message shows that your installation appears to be working correctly.
To generate this message, Docker took the following steps:
1. The Docker client contacted the Docker daemon.
2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
(amd64)
3. The Docker daemon created a new container from that image which runs the
executable that produces the output you are currently reading.
4. The Docker daemon streamed that output to the Docker client, which sent it
to your terminal.
(...)
Once you have verified these requirements, go to Installation and configuration for a step-by-step guide to install and configure your wis2box.