Development Environment Setup

The Dogebox exclusively runs on NixOS as its linux-base.

Install NixOS in a VM

There are multiple ways of accomplishing this. The easiest way by far is to use Orbstack which supports NixOS VMs natively, and provides useful filesystem and host-network sharing.

The rest of this guide will assume you are using Orbstack, or a VM solution that lets you bind to your hosts network interfaces.

Clone required repositories

There are 3 repositories that provide the foundational building blocks for Dogebox. Please git clone all of these.

• Dogeboxd - https://github.com/Dogebox-WG/dogeboxd.git
• DPanel - https://github.com/Dogebox-WG/dpanel.git
• DKM - https://github.com/Dogebox-WG/dkm.git

Please note: dogeboxd & dpanel must be cloned into the same parent directory. You can clone DKM anywhere.

Configure your Nix environment to use flakes

As we're using Nix flakes, a setup script needs to be run that replaces your existing NixOS system configuration with one that uses flakes. This will be done by the setup script, it will also adjust some other configurations like enabling experimental features.

Run the following within your NixOS environment:

nix run github:dogebox-wg/dev/#setup \
  --extra-experimental-features nix-command \
  --extra-experimental-features flakes

This script will step you through a few questions, please read each of them carefully.

Starting Services

You need to be running dogeboxd and dkm at the same time to have things working. dpanel is served via dogeboxd automatically, assuming they've been cloned into the same parent directory.

Both services contain a nix flake, which provide pre-configured devshells that have all the necessary dependencies for executing the service.

Both services also contain a Makefile that provides a dev command that run things in a "default" development mode.

Starting dogeboxd

cd dogeboxd
nix develop
make dev

Starting dkm

cd dkm
nix develop
make dev

dogeboxd should now be listening on two ports:

• Dogeboxd API will be listening at http://127.0.0.1:3000
• Dpanel UI will be listening at http://127.0.0.1:8080 and should be ready in setup mode.

After initial setup has completed, you will need to re-run make dev for dogeboxd to launch it again in normal-mode. Please see below for more details.

Things to note

• In development mode, any time the service would trigger a shutdown or restart, the dogeboxd process will exit instead.
• In development mode your dogeboxd/dpanel sessions will persist across service restarts. This will not happen in non-development mode.
• You can run make recovery to force dogeboxd into recovery mode.
• All data for both dogeboxd and DKM is written to ~/data. Deleting this directory will reset your state.