Box IO

Self-hosted IoT for Arduino and ESP32.

Install Box IO on BlueOnyx 5212R

BlueOnyx 5212R is AlmaLinux 10 with Apache already listening on ports 80 and 443. Box IO uses a separate compose file so those ports stay with the panel. The dashboard is a virtual site that proxies to the container. Arduino boards still use HTTP port 5923. The container is the Docker Hub image someone275/box_io-docker-server.

The Ubuntu, CentOS, Red Hat, and Raspberry Pi pages under Docker Install use a different compose file. Do not run that one on this server. It would try to bind ports 80 and 443.

1. Install Docker

Sign in as root over SSH. BlueOnyx turns SELinux off, which Docker needs on this panel.

dnf -y install dnf-plugins-core git
dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
dnf -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
systemctl enable --now docker
docker version
docker compose version

2. Download Box IO onto the server

Installing Docker does not create a Box IO folder. This step downloads it. git is already installed.

cd /root
git clone https://github.com/Someone275/Box_IO-Docker-server.git
cd /root/Box_IO-Docker-server
curl -fsSL -o docker-compose.blueonyx.yml https://box-io.com/station/docker-compose.blueonyx.yml
curl -fsSL -o keep-up.sh https://box-io.com/station/keep-up.sh
curl -fsSL -o blueonyx/boxio-proxy.inc https://box-io.com/station/boxio-proxy.inc
curl -fsSL -o blueonyx/install-proxy.sh https://box-io.com/station/install-proxy.sh
chmod +x keep-up.sh blueonyx/install-proxy.sh
ls docker-compose.blueonyx.yml .env.example keep-up.sh blueonyx/install-proxy.sh

The clone creates /root/Box_IO-Docker-server. If git says that folder already exists, skip the clone and run the curl lines from inside it. ls must print those four names. If pull still asks for ghcr.io, add BOXIO_IMAGE=someone275/box_io-docker-server:latest to .env.

3. Create the secret file

cd /root/Box_IO-Docker-server
cp .env.example .env
openssl rand -hex 48

Open .env and set JWT_SECRET to that hex string. One line, no quotes. Do not commit .env.

JWT_SECRET=paste_the_hex_here

4. Start the container

This compose file publishes the dashboard on 127.0.0.1:3847 only, and the device hub on 5923. docker compose pull downloads someone275/box_io-docker-server from Docker Hub. The panel does not compile Node.

cd /root/Box_IO-Docker-server
docker compose -f docker-compose.blueonyx.yml pull
docker compose -f docker-compose.blueonyx.yml up -d --no-build
docker compose -f docker-compose.blueonyx.yml ps
curl -sS http://127.0.0.1:3847/api/health

The health URL returns JSON with ok set to true. Nothing on the public ports 80 or 443 has moved.

5. Open port 5923

In the BlueOnyx GUI, open Server Management, then Security, then Firewall, and allow TCP 5923. The proxy script also adds that port in firewalld when firewalld is running. Boards use this port. They do not use 80 or 443.

6. Create the dashboard site

  1. In Site Management, create a virtual site for the dashboard name, such as boxio.example.com.
  2. Point DNS for that name at this server.
  3. Turn on SSL for the site and use the panel’s Let’s Encrypt button.
  4. Leave the site document root empty of a real site. Apache will proxy every request to Box IO.

7. Proxy the site to the container

cd /root/Box_IO-Docker-server
sh blueonyx/install-proxy.sh boxio.example.com

Replace boxio.example.com with the virtual site name. The script writes the proxy rules, reloads Apache, and allows TCP 5923. Open https://boxio.example.com and create the admin account.

The panel renews that site certificate. Do not add the Box IO renew-cert.sh crontab here. That job is for the nginx container on Ubuntu, CentOS, and Red Hat.

If Network Services, Web, Nginx has the SSL proxy turned on, the same script updates that site’s Nginx file so live pin updates can use the websocket. Saving the site in the GUI can rewrite those files. Run the script again if the dashboard stops loading or live updates freeze.

8. Connect a board

The sketch host is the server’s address, and the port is 5923. Example: http://203.0.113.10:5923. Create a device key in the dashboard and put it in BOXIO_AUTH. The rest of the setup matches the Docker page: a project, widgets, Save layout, then Live.

9. Update

cd /root/Box_IO-Docker-server
curl -fsSL -o docker-compose.blueonyx.yml https://box-io.com/station/docker-compose.blueonyx.yml
curl -fsSL -o keep-up.sh https://box-io.com/station/keep-up.sh
curl -fsSL -o blueonyx/boxio-proxy.inc https://box-io.com/station/boxio-proxy.inc
curl -fsSL -o blueonyx/install-proxy.sh https://box-io.com/station/install-proxy.sh
chmod +x keep-up.sh blueonyx/install-proxy.sh
docker compose -f docker-compose.blueonyx.yml pull
docker compose -f docker-compose.blueonyx.yml up -d --no-build
sh blueonyx/install-proxy.sh boxio.example.com

The Docker volume boxio-data keeps users, device keys, and layouts. docker compose pull does not delete it.

10. Export and import this station

Use this to move the station you are running now onto another machine. Export writes one archive and starts the station again. On the next machine, import replaces the database, the license, and the JWT secret. Keep the archive private and delete it after the import.

cd /root/Box_IO-Docker-server
sh scripts/export-data.sh -f docker-compose.blueonyx.yml -o ~/boxio-export.tar.gz

Copy boxio-export.tar.gz to the next server, then from /root/Box_IO-Docker-server there:

sh scripts/import-data.sh -f docker-compose.blueonyx.yml ~/boxio-export.tar.gz
curl -sS http://127.0.0.1:3847/api/health
rm -f ~/boxio-export.tar.gz

Sign in with the same admin account. Device keys and layouts are in the database. Run sh blueonyx/install-proxy.sh boxio.example.com again if the dashboard site is new.