Edgehog Just in Time

Introduction

Why spend 5 minutes setting up Edgehog when you can do it just right? This tutorial will guide you through setting up Edgehog using the justfile.

Prerequisites

Before we get started, make sure you have the following tools installed:

  • Git: For cloning repositories
  • Docker: For running containers
  • Docker Compose: For orchestrating services
  • astartectl: For managing Astarte (installation guide)
  • just: The command runner that makes this all possible. You can install it using asdf, your system package manager, or follow the official installation guide
  • Rust toolchain (optional, only needed for connecting devices): You can install it using asdf, rustup, or your preferred method

Clone the Edgehog Repository

First, clone the Edgehog repository and navigate into it:

$ git clone https://github.com/edgehog-device-manager/edgehog && cd edgehog

Discover Available Commands

The beauty of just is its discoverability. See all available commands with:

$ just --list

Or simply:

$ just help

This will show you all the recipes (tasks) available in the justfile, nicely organized by category.

Setting Up Your Environment

To set up the complete Edgehog stack with Astarte and a test tenant, run:

$ just provision-tenant

This single command will:

  1. ✅ Check system prerequisites
  2. 🔧 Configure system settings (adjusting aio-max-nr if needed)
  3. 🌟 Clone and initialize Astarte
  4. 🏠 Create an Astarte test realm
  5. 🚀 Start Edgehog services
  6. 👤 Create a test tenant in Edgehog
  7. 🌐 Automatically open the dashboards in your browser

Sit back, relax, and watch the magic happen!

Other setup options: If you need more granular control, check out the available commands with just --list or just help.

Accessing the Dashboards

After provisioning, your dashboards should open automatically. If not, or if you closed them, just run:

$ just open-dashboards

This will open:

You'll be automatically logged in with the appropriate JWT tokens!

Connecting a Device

Want to see Edgehog in action with a real (simulated) device? It's just one command away:

$ just connect-device

This will:

  1. 🔍 Check Rust prerequisites
  2. 📦 Clone the Edgehog Device Runtime repository
  3. 📝 Register a new device with Astarte
  4. ⚙️ Generate the device configuration
  5. 🚀 Start the device runtime

Your device will start sending telemetry data to Edgehog. Watch it appear in the Edgehog dashboard!

Note: If you encounter issues with the device runtime, check the OS requirements documentation for system-specific setup details.

Reconnecting the Same Device

Already have a device configured but want to restart it with a clean state? Use:

$ just reconnect-device

This command:

  • ✅ Uses your existing device configuration (no re-registration needed)
  • 🧹 Cleans device state (.store/ and .updates/ directories)
  • 🚀 Starts the device runtime with existing build artifacts
  • ⚡ Fast startup - no compilation or registration overhead!

If no device is configured yet, it will automatically run just connect-device to set everything up.

Connecting a New Device

Want to test with multiple devices? Register and connect a new device with:

$ just new-device

This command:

  • 📝 Registers a new device with Astarte (new device ID and credentials)
  • 🧹 Cleans previous device state
  • ⚙️ Generates fresh device configuration
  • 🚀 Starts the device runtime
  • ⚡ Reuses compiled runtime - faster than full connect-device!

This is perfect for testing scenarios with multiple devices without waiting for a full recompilation.

Running Multiple Devices: You can run multiple devices simultaneously by using separate terminals! Once a device is running, it has its own runtime context in memory. Simply open a new terminal, run just new-device to register a different device (which overwrites the config file), and both devices will run in parallel. Each device maintains its own state since they have unique device IDs.

Important: Remember that all simulated devices are running on the same physical hardware (your PC/laptop). Features that require exclusive access to the same hardware resources may conflict or fail when running multiple devices simultaneously.

Development Workflows

Running Backend in Development Mode

Want to work on the Edgehog backend? Start it in development mode:

$ just dev-backend

This will:

  • ✅ Ensure Astarte is running
  • 🐘 Start supporting services (PostgreSQL, MinIO, Registry)
  • 🔥 Run the backend with mix phx.server for hot reloading
  • 🌐 Make the API available at http://localhost:4000

Running Frontend in Development Mode

To work on the frontend:

$ just dev-frontend

This starts the Vite dev server with hot module replacement at http://localhost:5173.

Running Both in Parallel

Open two terminal windows and run:

# Terminal 1
$ just dev-backend

# Terminal 2
$ just dev-frontend

Monitoring Your Services

Check Service Status

Want to see what's running?

$ just status

This shows:

  • All running Docker containers
  • Health check status for all services

View Logs

To tail logs from all Edgehog services:

$ just logs

Or just Astarte services:

$ just logs-astarte

Cleaning Up

Tear Down Everything

When you're done and want to clean up completely:

$ just deprovision-tenant

This removes:

  • All Edgehog services and volumes
  • All Astarte services and volumes
  • Generated files and directories
  • Device runtime files

Keep Astarte, Remove Edgehog

If you want to keep Astarte running but clean up Edgehog and device runtime:

$ just deprovision-edgehog

This is useful when you want to restart Edgehog fresh while keeping your Astarte realm intact.

Troubleshooting

Services Not Starting

Check the status first:

$ just status

If services are down, check the logs:

$ just logs

Conclusion

With just, setting up Edgehog is... well, just easy! No more remembering complex Docker commands or multi-step setup procedures. Just run just provision-tenant and you're ready to manage your IoT devices.

Remember: when in doubt, just help will show you the way!

Pro tip: You can create your own custom recipes in the justfile. It's just a regular text file with a simple syntax. Check out the just documentation to learn more.