devprincekumar/edgeshell repository overview

⁠EdgeShell

Self-hosted fleet management for Raspberry Pi and edge devices. One secure web portal to monitor, control and deploy to your whole fleet over SSH and Ansible: live metrics, web terminal, file deployment, log browser, remote desktop, Node-RED access, bulk onboarding and role-based access.

⁠Production setup (recommended)

EdgeShell behind nginx⁠, with MariaDB, privacyIDEA⁠ for mandatory two-factor authentication and certbot for Let's Encrypt, in one Compose file. nginx is the only container with published ports; everything else is on internal Docker networks. All state lives in a ./data folder on the host, so backups, upgrades and moving to another server are a folder copy.

You need: a Linux host with Docker and the Compose plugin, and port 80 open to the internet (plus 443 once you add a domain).

mkdir -p edgeshell/nginx && cd edgeshell
base=https://raw.githubusercontent.com/855princekumar/edgeshell/main/docker
curl -fsSLO $base/compose.yaml
curl -fsSLo nginx/entrypoint.sh $base/nginx/entrypoint.sh
curl -fsSLo nginx/certbot.sh $base/nginx/certbot.sh
curl -fsSLO $base/lake-init.sh
curl -fsSLo .env $base/.env.example && chmod 600 .env

# Generate the eight secrets
for k in SECRET_KEY CREDENTIAL_KEY DB_PASSWORD DB_ROOT_PASSWORD MFA_ADMIN_PASSWORD MFA_PEPPER MFA_DB_PASSWORD MFA_SECRET_KEY; do
  sed -i "s|^$k=.*|$k=$(openssl rand -hex 32)|" .env
done

docker compose up -d

Open http://<server IP> and sign in as admin / admin123. Before anything else you set up two-factor authentication (scan the QR code with any authenticator app and save the 10 backup codes), your personal email (where password reset links go) and a new password.

MQTT heartbeat (optional): set HEARTBEAT_MASTER_KEY and SENSEHIVE_API_TOKEN in .env (openssl rand -hex 32 each). Then install the heartbeat agent from Fleet Setup: nodes send encrypted heartbeats over a public broker to SenseHive (in the stack), so a VPN glitch is not counted as downtime. See docs/HEARTBEAT.md⁠.

Email (optional): set PUBLIC_URL and the SMTP_* values in .env (any SMTP server; free options such as Resend, Brevo, useSend or Gmail are explained in docs/EMAIL.md⁠). Every user then confirms their email with a link, anyone can reset their password by email (2FA stays on), and ticket notifications are mailed. Without them, administrators recover with a backup code, and other users ask an administrator.

Adding a domain (HTTPS): point its DNS A record at the server, open port 443, then set in .env:

EDGESHELL_DOMAIN=fleet.yourdomain.com
[email protected]
SESSION_COOKIE_SECURE=true
PUBLIC_URL=https://fleet.yourdomain.com

and run docker compose up -d. certbot gets the certificate within a minute and nginx switches to HTTPS by itself (HTTP and the bare IP then redirect to the domain). Renewal is automatic and all data in ./data is kept.

HTTPS without a domain: use the server's public IPv4 address as EDGESHELL_DOMAIN (with SESSION_COOKIE_SECURE=true and PUBLIC_URL=https://<ip>). Let's Encrypt issues free short-lived certificates for IP addresses (about 6 days); certbot renews them automatically. Use a static address (an Elastic IP on AWS), since the certificate names the IP.

Harden the host (fail2ban for SSH and the web, key-only SSH, log rotation, automatic security updates):

curl -fsSLO $base/host-hardening.sh
sudo bash host-hardening.sh --admin-ip <your public IP>   # never ban yourself

Keep your SSH session open and test a new login before closing it.

Live VPN status: with Tailscale on the host, the admin panel's VPN page shows the tailnet live through the host's tailscaled socket (read-only).

⁠What you get

Containers start in order and only when the one before is healthy, and all restart automatically after a crash or a host reboot.

⁠Where your data lives

edgeshell/
├── compose.yaml
├── nginx/               entrypoint.sh (generates the site config), certbot.sh
├── .env                 settings and secrets (chmod 600)
└── data/
    ├── mariadb/         database
    ├── instance/        app state
    ├── uploads/         files staged for deployment
    ├── privacyidea/     2FA encryption key and audit keys (back up with .env)
    ├── letsencrypt/     TLS certificates and keys
    └── certbot-www/     ACME challenge files

⁠Configuration (.env)

The app refuses to start if any required value is missing.

⁠Operate

⁠Upgrading from 1.2.x or 1.3.x

1.3.0 added the privacyidea and mfa-db-init services and replaced Caddy with nginx and certbot; 1.3.2 adds MFA_SECRET_KEY. Fetch the current files, add any missing secrets to your existing .env (the loop below only adds what is missing), then start as usual. Users, nodes, passwords and 2FA enrollments are kept; coming from 1.2.x, everyone sets up 2FA at their next sign-in:

base=https://raw.githubusercontent.com/855princekumar/edgeshell/main/docker
mkdir -p nginx
curl -fsSLO $base/compose.yaml
curl -fsSLO $base/host-hardening.sh
curl -fsSLo nginx/entrypoint.sh $base/nginx/entrypoint.sh
curl -fsSLo nginx/certbot.sh $base/nginx/certbot.sh
curl -fsSLO $base/lake-init.sh
sed -i 's|^EDGESHELL_DOMAIN=:80$|EDGESHELL_DOMAIN=|' .env    # IP mode is now an empty value
for k in MFA_ADMIN_PASSWORD MFA_PEPPER MFA_DB_PASSWORD MFA_SECRET_KEY; do
  grep -q "^$k=" .env || echo "$k=$(openssl rand -hex 32)" >> .env
done
sed -i 's|^EDGESHELL_TAG=.*|EDGESHELL_TAG=1.17.0|' .env
docker compose pull && docker compose up -d --remove-orphans   # removes the old caddy container

With a domain already set, certbot requests a new certificate on the first start (Caddy's certificates are not reused); keep port 80 open.

⁠Reaching your fleet

EdgeShell connects to nodes over SSH. Run your mesh VPN (Tailscale⁠ or WireGuard) on the host: containers reach tailnet addresses through the host. Nodes published on the host itself are reachable as host.docker.internal.

⁠Quick try (single container)

docker run -d --name edgeshell -p 5000:5000 \
  -e SECRET_KEY="$(openssl rand -hex 32)" \
  -e CREDENTIAL_KEY="$(openssl rand -hex 32)" \
  -e SESSION_COOKIE_SECURE=false \
  -v edgeshell_instance:/app/instance -v edgeshell_uploads:/app/uploads \
  devprincekumar/edgeshell:latest

Open http://localhost:5000⁠. This uses SQLite and plain HTTP: fine for a test on your machine, not for production. Note the CREDENTIAL_KEY you used if you keep the volumes.

⁠Try it against a simulated fleet

Pi Fleet Emulator⁠ spawns Raspberry Pi-like nodes with real SSH and Node-RED (32/64-bit, Buster to Bookworm). Export its fleet as JSON and import it in EdgeShell under Nodes → Import.

⁠Security

• Required secrets, or the container will not start
• Login lockout, rate limiting, identical errors for unknown users
• One device per user by default (admins can allow up to 4); password resets and "sign out everywhere" end sessions immediately
• CSRF protection on every change; Secure, HttpOnly, SameSite cookies behind HTTPS
• Every release is published by CI only after unit tests, a secret scan, an image audit and an end-to-end run against an emulated fleet pass on both amd64 and arm64

Report vulnerabilities privately: see SECURITY.md⁠.

⁠Tags