All guides

Self-host an IoT server on Ubuntu

You can run the Plynx server on a small Ubuntu VPS or on a machine at home. Your ESP32 and ESP8266 boards connect to that server, and Plynx uses it for dashboards, widget state and project history.

This guide has two installation paths. Choose the VPS path if the server should be reachable from the internet. Choose the local path if the server stays on your home network, with Tailscale for access from outside. Follow one path only.

If you are using a Raspberry Pi, follow the Raspberry Pi guide. This article assumes Ubuntu 22.04 or 24.04 on a VPS, home server or NAS.

How the setup works

The installation has three parts.

  1. Your boards connect to the server on port 8080.
  2. The server runs as one JAR file. It stores projects, widget state and history in its data directory. It is a GPL-3.0 fork of the final open source Blynk local server. The current release is 0.41.18, and the source and release files are at github.com/NickP005/plynx-server.
  3. Your iPhone runs Plynx and connects to the same server on port 9443.

You do not need a Plynx Cloud account for this setup.

What you need

  • A machine running Ubuntu 22.04 or 24.04. A small VPS or a home server is enough for a personal project: the server uses between 100 and 200 MB of memory after it starts, and 1 GB of RAM leaves plenty of room.
  • SSH access to that machine through an account that can run sudo.
  • For a VPS, optionally a domain name, if you want a Let’s Encrypt certificate.
  • For a home server, its LAN address. Tailscale is optional if you want to reach Plynx while away from home.

Run the commands below in an SSH session on the server, not on your laptop. Each block can be pasted whole.

Path A: a VPS reachable from the internet

Replace you@example.com with your email address and choose-a-long-password with the password for the server’s admin account. If you use a domain, replace iot.example.com with it.

1. Install Java and the required tools
sudo apt update && sudo apt upgrade -y
sudo apt install -y default-jre-headless ufw curl wget
java -version

Plynx needs Java 11 or later: Ubuntu 22.04 installs 11, Ubuntu 24.04 installs 21, and both work. Continue when java -version prints a version number.

2. Download the server and write its configuration

This block creates a service account, downloads the release, checks it against its published SHA256 and writes the configuration file.

sudo useradd --system --no-create-home --home-dir /opt/plynx --shell /usr/sbin/nologin plynx
sudo install -d -o plynx -g plynx -m 755 /opt/plynx
sudo install -d -o plynx -g plynx -m 700 /opt/plynx/data
cd /opt/plynx
sudo wget -q https://github.com/NickP005/plynx-server/releases/download/v0.41.18/plynx-server-0.41.18.jar
sudo wget -q https://github.com/NickP005/plynx-server/releases/download/v0.41.18/plynx-server-0.41.18.jar.sha256
sha256sum -c plynx-server-0.41.18.jar.sha256 && sudo ln -sf plynx-server-0.41.18.jar plynx-server.jar

sudo tee /opt/plynx/server.properties > /dev/null <<'EOF'
admin.email=you@example.com
admin.pass=choose-a-long-password
allowed.administrator.ips=127.0.0.1/32,::1/128
server.ssl.cert=/opt/plynx/certs/fullchain.pem
server.ssl.key=/opt/plynx/certs/privkey.pem
server.ssl.key.pass=
EOF
sudo chown plynx:plynx /opt/plynx/server.properties
sudo chmod 600 /opt/plynx/server.properties

sha256sum must print OK; if it does not, the link is not created and the download should be repeated. The admin panel only answers connections that come from the server itself: the questions at the end show how to open it through SSH.

The certificate files do not exist yet. Until they do, the server uses a certificate it generates on its own, and the Plynx app connects with that one too. Step 5 replaces it with a Let’s Encrypt certificate.

3. Create the systemd service and start it
sudo tee /etc/systemd/system/plynx-server.service > /dev/null <<'EOF'
[Unit]
Description=Plynx IoT server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=plynx
Group=plynx
WorkingDirectory=/opt/plynx
ExecStart=/usr/bin/java -jar /opt/plynx/plynx-server.jar \
  -serverConfig /opt/plynx/server.properties \
  -dataFolder /opt/plynx/data
Restart=on-failure
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now plynx-server
for i in $(seq 30); do sudo journalctl -u plynx-server --no-pager | grep -m1 "successfully started" && break; sleep 2; done

The last command prints a line ending in successfully started. If it prints nothing within a minute, run sudo journalctl -u plynx-server -n 50 to read the error.

4. Open the firewall

Port 8080 is where your boards connect. Port 9443 is where the app connects.

sudo ufw allow OpenSSH
sudo ufw allow 8080/tcp comment 'Plynx boards'
sudo ufw allow 9443/tcp comment 'Plynx app'
sudo ufw --force enable
sudo ufw status

Many VPS providers also have a firewall in their control panel. If yours does, open the same two ports there.

5. Add a Let’s Encrypt certificate (optional)

This step needs a domain with an A record pointing to the VPS. The app works without it; a real certificate matters for browsers and for anything else that checks certificates.

The block requests the certificate, installs a hook that copies it where the server can read it after every renewal, and runs the hook once.

getent hosts iot.example.com

sudo apt install -y certbot
sudo certbot certonly --standalone --non-interactive --agree-tos \
  -m you@example.com -d iot.example.com \
  --pre-hook "ufw allow 80/tcp" --post-hook "ufw delete allow 80/tcp"

sudo mkdir -p /etc/letsencrypt/renewal-hooks/deploy
sudo tee /etc/letsencrypt/renewal-hooks/deploy/plynx.sh > /dev/null <<'EOF'
#!/bin/sh
set -e
LIVE=/etc/letsencrypt/live/iot.example.com
install -d -o plynx -g plynx -m 700 /opt/plynx/certs
install -o plynx -g plynx -m 600 "$LIVE/fullchain.pem" /opt/plynx/certs/fullchain.pem
install -o plynx -g plynx -m 600 "$LIVE/privkey.pem" /opt/plynx/certs/privkey.pem
systemctl restart plynx-server
EOF
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/plynx.sh
sudo /etc/letsencrypt/renewal-hooks/deploy/plynx.sh

The first line must print your VPS address; if it does not, wait for DNS before running the rest. Certbot opens port 80 only while it verifies the domain, now and at every renewal. It renews the certificate on its own timer, and the hook restarts the server afterwards, which takes a few seconds. sudo certbot renew --dry-run tests the whole cycle.

6. Check the server from another machine

Run this on your laptop, with your domain or the VPS address.

nc -zv iot.example.com 8080
nc -zv iot.example.com 9443
echo | openssl s_client -connect iot.example.com:9443 -servername iot.example.com 2>/dev/null \
  | openssl x509 -noout -issuer -enddate

Both nc lines must report a successful connection. If one hangs, check the firewall and the provider’s control panel. After step 5, the issuer is Let’s Encrypt; without it, the issuer is CN=localhost.

Path B: a local Ubuntu server or NAS

This path keeps the server on your LAN. It does not need a public IP address or a domain. Tailscale adds secure access from outside your home.

Replace you@example.com and choose-a-long-password as in Path A, and 192.168.1.0/24 with your own subnet.

1. Install Java and the firewall
sudo apt update && sudo apt upgrade -y
sudo apt install -y default-jre-headless ufw curl wget
java -version
2. Download the server and write its configuration
sudo useradd --system --no-create-home --home-dir /opt/plynx --shell /usr/sbin/nologin plynx
sudo install -d -o plynx -g plynx -m 755 /opt/plynx
sudo install -d -o plynx -g plynx -m 700 /opt/plynx/data
cd /opt/plynx
sudo wget -q https://github.com/NickP005/plynx-server/releases/download/v0.41.18/plynx-server-0.41.18.jar
sudo wget -q https://github.com/NickP005/plynx-server/releases/download/v0.41.18/plynx-server-0.41.18.jar.sha256
sha256sum -c plynx-server-0.41.18.jar.sha256 && sudo ln -sf plynx-server-0.41.18.jar plynx-server.jar

sudo tee /opt/plynx/server.properties > /dev/null <<'EOF'
admin.email=you@example.com
admin.pass=choose-a-long-password
allowed.administrator.ips=127.0.0.1/32,::1/128,192.168.1.0/24
EOF
sudo chown plynx:plynx /opt/plynx/server.properties
sudo chmod 600 /opt/plynx/server.properties

sha256sum must print OK. The server generates its own certificate at every start, and the Plynx app connects with it: there is nothing to set up for TLS on a LAN.

3. Create the systemd service and start it
sudo tee /etc/systemd/system/plynx-server.service > /dev/null <<'EOF'
[Unit]
Description=Plynx IoT server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=plynx
Group=plynx
WorkingDirectory=/opt/plynx
ExecStart=/usr/bin/java -jar /opt/plynx/plynx-server.jar \
  -serverConfig /opt/plynx/server.properties \
  -dataFolder /opt/plynx/data
Restart=on-failure
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now plynx-server
for i in $(seq 30); do sudo journalctl -u plynx-server --no-pager | grep -m1 "successfully started" && break; sleep 2; done
4. Allow connections from your LAN
sudo ufw allow OpenSSH
sudo ufw allow from 192.168.1.0/24 to any port 8080 proto tcp comment 'Plynx boards'
sudo ufw allow from 192.168.1.0/24 to any port 9443 proto tcp comment 'Plynx app'
sudo ufw --force enable
sudo ufw status
5. Reach the server from outside with Tailscale (optional)

Install Tailscale on the Ubuntu server and on your iPhone. You get a private address that works from anywhere, without opening a port on your router.

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
sudo ufw allow in on tailscale0 comment 'Tailscale devices'
tailscale ip -4

The ufw line matters: the rules from step 4 only admit your LAN, and the phone arrives from a Tailscale address. The last command prints the server’s Tailscale address, which looks like 100.x.y.z. Use it in Plynx when you are away from home. Boards on the home network keep using the LAN address.

Connect Plynx and your boards

The app

Install Plynx from the App Store. On the sign-in screen, tap Server, choose Private Server, and enter your server’s address with port 9443.

  • On a VPS, use your domain or the VPS address.
  • On a home server, use its LAN address, or its Tailscale address when you are away.

Create an account. It is stored on your server. Then create a project, add a Button widget on virtual pin V1 and copy the authentication token from the project settings.

The board

In a Plynx sketch, pass your server address and port 8080 as the last two arguments of Plynx.begin.

#define PLYNX_PRINT Serial
#include <WiFi.h>
#include <PlynxSimpleEsp32.h>

char auth[] = "YOUR_AUTH_TOKEN";
char ssid[] = "YOUR_WIFI";
char pass[] = "YOUR_WIFI_PASSWORD";

void setup() {
  Serial.begin(115200);
  Plynx.begin(auth, ssid, pass, "iot.example.com", 8080);
}

void loop() {
  Plynx.run();
}

Install the Plynx library from the Arduino Library Manager and flash the board once over USB. Once it connects, tapping the button in Plynx sends the command through your server to the board.

Back up the data directory

Plynx stores everything in /opt/plynx/data. This script keeps one archive for each day of the week and overwrites it the following week.

sudo tee /etc/cron.daily/plynx-backup > /dev/null <<'EOF'
#!/bin/sh
DEST=/var/backups/plynx
mkdir -p "$DEST"
tar czf "$DEST/plynx-data-$(date +%u).tar.gz" -C /opt/plynx data server.properties
EOF
sudo chmod +x /etc/cron.daily/plynx-backup
sudo /etc/cron.daily/plynx-backup && ls -lh /var/backups/plynx

Copy the archives to another machine or backup service. A backup stored only on the server does not protect you from losing that server.

Keep it up to date

The JAR does not update itself. Keep Ubuntu patched, and when a new release appears on GitHub, download it next to the old one and move the link. Replace 0.41.19 with the new version number.

V=0.41.19
cd /opt/plynx
sudo /etc/cron.daily/plynx-backup
sudo wget -q https://github.com/NickP005/plynx-server/releases/download/v$V/plynx-server-$V.jar
sudo wget -q https://github.com/NickP005/plynx-server/releases/download/v$V/plynx-server-$V.jar.sha256
sha256sum -c plynx-server-$V.jar.sha256 && sudo ln -sf plynx-server-$V.jar plynx-server.jar \
  && sudo systemctl restart plynx-server

The old JAR stays in the folder: pointing the link back at it and restarting undoes the upgrade.

Questions people ask

Do I need a domain name?

No. Boards and the app can use the server’s IP address. A domain is needed for a Let’s Encrypt certificate, and it keeps working if your VPS ever gets a new address.

What is different from Plynx Cloud?

Dashboards, widgets, pin history and board connections work the same. Three things run on Plynx Cloud only: push notifications to the App Store app, over-the-air updates from the web editor, and Archimedes, the assistant. The self-hosted release does not include the last two yet.

Can other people sign up on my server?

Anyone who can reach port 9443 can create an account: the server has no invitation list. On the home path that means only your LAN and your Tailscale devices. On a VPS, if you want the same privacy, install Tailscale there too and allow port 9443 only on the tailscale0 interface.

How do I open the admin panel?

The configuration above lets it answer only from the server itself. Open an SSH tunnel with ssh -L 9443:127.0.0.1:9443 you@your-server, then visit https://127.0.0.1:9443/admin in your browser and sign in with the admin email and password from server.properties.

What if my ISP blocks incoming connections?

Use the local path with Tailscale. Nothing on your router needs to be opened. Boards at home reach the server on the LAN, and your phone reaches it through the Tailscale address.

Can I run this in Docker?

The release is a plain JAR, so any image with Java 11 or later runs it. Mount the data directory as a volume and publish ports 8080 and 9443.

Can I move from a home server to a VPS later?

Yes. Install the server on the new machine the same way, stop both services, copy /opt/plynx/data across, and start the new one. Your projects, tokens and history come with the data folder. Then point the app and the boards at the new address.

Does it replace an MQTT broker?

No. Boards speak the Plynx protocol on port 8080. The server also listens on port 8440 for a minimal MQTT connection that only accepts pin writes, which is not a substitute for a broker like Mosquitto. If your other devices use MQTT, run a broker next to Plynx.

What you now control

Your boards, server, dashboards and project history now run on infrastructure you choose. A local installation keeps working on the LAN when the internet connection is down.

Plynx is free on the App Store. Point it at the server you set up and build dashboards for your own projects.