DogeBox - Dogecoin Blockchain in a Box

What is the Dogebox project?

Dogebox is a Linux server distribution and custom server software built specifically to meet the needs of the Dogecoin community.

The objective: to provide a decentralised platform for the development, distribution and self-hosting of software (we call them PUPs) that will bring real utility to the Dogecoin ecosystem and drive adoption.

>>> Join the Dogebox Developer Discord for Help <<<

What's in the box?

Dogebox is a locked down custom configuration of NixOS Linux which includes a number of Dogecoin specific services that combined deliver the Dogebox UI, the DRE (Doge Runtime Environment), Pup management and secure interaction between Pups.

Dogeboxd - Pup management and runtime orchestration

https://github.com/dogeorg/dogeboxd

Dogebox runs a daemon process 'dogeboxd' which provides installation and orchestration of Pups which are run in isolated containers via Linux Systemd / Linux Namespaces.

Dogeboxd manages inter-pup communications via nix-config rules, exposing TCP ports between containers, and proxying REST APIs as required for Pups to communicate with their dependencies, in accordance with their manifest rules.

This is all done in aid of providing an easy to use platform for Dogecoin users that can provide a secure runtime environment for Dogecoin adventurers who are not Linux administrators.

DPanel - Admin UI

https://github.com/dogeorg/dpanel

The Dogebox is managed via a convenient Web control panel that allows the user to install new Pups from the community, determine how they can communicate with eachother and the network, and then ensure they are running and monitored.

DKM - Doge Key Manager

https://github.com/dogeorg/dkm

The DKM provides cryptographic authentication to the Dogebox and Dogecoin key management for Pups in a manner that lets the user recover and control any keys generated by pups, via the use of hierarchical deterministic keys.

Each Pup installed is issued a 'delegated' child key from the Dogebox user's master key. Pups can then use these keys to derive further child keys for use as pay-to addresses or anything else such as providing full wallet functionality, online shops, etc.

DKM creates an encrypted master key and generates (derives) private-public keypairs for pups and other parts of the DogeBox ecosystem.

Keys are encrypted at rest with the DogeBox password and stored on disk.

Passwords are first hashed using Argon2 memory-hard KDF (Argon2id variant) with parameters time=3, memory=64M, threads=4 and the BLAKE2b hash function as recommended in RFC 9106.

The password-derived hash is then used to encrypt the master key with ChaCha20 cypher and Poly1305 Authenticated Encryption (AE) scheme.

Keys in DKM are only in memory while they are actively being used for Authentication or key derivation.

Dogenet - Multi-protocol gossip network

https://github.com/dogeorg/dogenet

DogeNet is a service that implements the Doge Gossip Protocol, which is a multi-channel protocol for communicating among Dogenet nodes.

It is a foundational piece for future experimental protocols (Project Sakura), and provides useful side-channels for Dogecoin adjacent projects to communicate without polluting the Dogecoin blockchain, where simple peer-to-peer communication is sufficient.

DogeNet builds a database of active DogeBox nodes, which is used to find peer nodes to connect to. DogeNet maintains a connection to at least 6 peers at all times (more if running novel protocol-handlers that require connecting to other participating nodes.)

DogeNet exposes a local UNIX-domain socket for custom Protocol Handlers to connect to DogeNet and send/receive messages on any channels they're interested in.

Channels are assigned to different protocols; for example, DogeNet nodes announce their presence and public address on the ''Node' channel; DogeBoxes can optionally announce an identity profile on the ''Iden' channel, for display on the DogeMap and for use in future social pups.

Installation

Pre-installed hardware

The Dogecoin Foundation offers pre-installed NanoPC-T6's running Dogebox which are available for purchase at dogebox.dogecoin.org.

Dogebox

DIY

Dogebox is available as a bare-metal Linux install or as a virtual machine image for a number of platforms. Dogebox is also developed to run natively on the FriendlyElec NanoPC-T6 and a number of other ARM SBCs.

FriendlyElec NanoPC-T6

DIY Installation options

There are various options for installing Dogebox on your own system, for direct help be sure to join the Developer Discord Server

Initial Setup

On first-boot your Dogebox will enter Setup Mode

TBD

Virtual Machines

Download images

Head over to https://github.com/dogeorg/dogebox/releases and download the appropriate image for your VM platform.

Steps to run on VirtualBox

  1. Download Virtualbox, or another OVA compatible VM launcher.

  2. Import the OVA image by selecting the file you downloaded from the latest release.

import OVA

  1. Ensure the VM has sufficient RAM for the software you plan to run on the Dogebox.

Set RAM

  1. Once imported, click 'Settings' and configure your network to use 'bridged mode'.

import OVA

  1. Launch the VM. This may take up to 10 minutes depending on your internet connection, to configure itself initially, grab a cuppa.

import OVA

  1. Login with username: shibe and password: suchpass, then run ip addr, it may look different to this but skip the first loopback interface 'lo' and look for the highlighted IP, in this example: 192.168.1.5

import OVA

  1. Open your browser and visit http://<ip>:8080 to visit the setup experience and configure your dogebox.

FriendlyElec T6 ARM Hardware installer

An alpha release of the Dogebox OS built specifically for the FriendlyElec NanoPC-T6.

IMGs HERE >> https://github.com/dogeorg/dogebox/releases/tag/v0.1.1-beta-t6.1

Dogebox

Things to note / What does not work

These things will all be fixed in a following release. This release is for tinkerers that are happy to re-flash a couple of times before a stable T6 release.

  • The T6 bootloader only supports booting from MicroSD cards that are 32GB and smaller (SDHC, not SDXC)
  • There is no storage selector. You must manually install NixOS to the internal EMMC (or NVME drive, if you have one installed) if you want to install anything that requires more disk space (eg. Dogecoin Core)
  • WiFi configuration during initial setup is currently not supported. The box must be connected to ethernet when you first boot Dogebox OS.

How to flash MicroSD using dd if=

  • Download the .img.gz file attached to the release.
  • Uncompress the image so you get the raw .img file.
  • On Linux & MacOS, use dd if= to write the file to the raw MicroSD device.
  • On Windows, use a raw image disk writer UI. There are multiple available.

How to flash MicroSD using Rufus

You can easly flash using the OpenSource Rufus Tool that you can get the latest version here for your operating system: https://github.com/pbatard/rufus/releases

  • Open Rufus
  • On Device select your Micro SD card
  • Click on Select and Choose the file you downloaded and decompressed .img
  • Click on Start and wait a few minutes to finish

How to Setup

  • Ensure you have an ethernet cable plugged into your T6 box.
  • Insert the MicroSD card
  • Make sure the HDMI cable is plugged into HDMI1
  • Plug power in.
  • Wait until the box finishes booting, this could take anywhere from 2 to 10 minutes.
  • Once finished, login with the username shibe and the password suchpass
  • Run ip addr and take note of the address.
  • Visit http://ip:8080 to start configuring your dogebox.

x86 Hardware Installer

x86 images are coming soon, please try our VM images for now.

Building Dogebox

Building images for Dogebox requires the Dogebox repository

https://github.com/dogeorg/dogebox/

For help building images be sure to join Developer Discord Server

SD and SD installer images for the NanoPC-T6

Start by building a disk image containing the root filesystem. Assuming you are in an environment containing nix-shell, from the root of this repository run

nix-shell
make nanopc-T6

Take a note of the location of the built image.

The SD images are built with a fork of FriendlyElec's sd-fuse_rk3588 for now. The following steps will be automated or replaced.

SD

Clone sd-fuse and create a directory for the components

git clone https://github.com/dogeorg/sd-fuse_rk3588 https://github.com/dogeorg/sd-fuse_rk3588.git
cd sd-fuse_rk3588
mkdir nixos-arm64

sd-fuse wants an android sparse image and we have a raw full-disk image. The following mount command mounts the partition inside the full disk image and build-rootfs-img.sh builds an android sparse image from the mounted directory and puts the result in nixos-arm64/rootfs.img

If /mnt is in use, use another location for the temporary mount.

mount -o loop,offset=$((2048 * 512)) <location of the image created in the first step> /mnt
./build-rootfs-img.sh /mnt nixos-arm64
umount /mnt

You can use prebuilt artifacts from this point, but if you intend to build the u-boot bootoarder from source, clone it's repository. If aarch64 cross compiling is not set up, the build script shoul fail with instructions containing what it's looking for.

cd out
git clone https://github.com/dogeorg/uboot-rockchip.git uboot-rk3588
cd uboot-rk3588
git checkout nanopi6-v2017.09
cd ../../
./build-uboot.sh nixos-arm64 nanopc-t6

Add any remaining artifacts to the 'nixos-arm64' directory

idbloader.img
uboot.img
misc.img
dtbo.img
resource.img
kernel.img
boot.img

Run the image builing script

./mk-sd-image.sh nixos-arm64

This will output an image to out/<rk3588-sd-nixos-arm64-YYYYMMDD.img>

u-boot's 'distro boot' expects to find an active partition, so we'll need to set that flag on the rootfs partition.

fdisk <image>
x
A
8
r
w

Container/VM images

Quick notes on building a container or VM image from a configuration.nix file:

  • Make sure the configuration.nix doesn't mention a bootloader, an appropriate one is included automatically and one defined here can conflict.

  • Install nixos-generators, if you have the nix package manager or are running NixOS you can just run 'nix-shell -p nixos-generators'

  • Build the desired image with nixos-generate -c configuration.nix -f $format

Tested image formats include: docker, install-iso, iso, lxc, lxc-metadata, proxmox-lxc, qcow, vmware

  • The build output should tell you the name and location of the built image.

'docker' for docker/podman

Use docker import or 'podman import' to generate a container image. You will need to manually specify a run CMD.

'install-iso / iso' for optical media images

Generates a bootable iso, install-iso will give you an installer, iso will be a live CD.

'lxc / lxc-metadata, proxmox-lxc' for linux containers

Use lxc and lxc-metadata for a manual container, or load the file generated by proxmox-lxc as a CT template to generate a container in proxmox.

'qcow' for qemu qcow2

Can be used as a disk image for qemu.

'vmware' for VMWare and VirtualBox

Generates a VMDK file that can be used by VMware or VirtualBox VMs directly

If you'd prefer a VDI, you can convert with VBoxManage clonehd --format VDI <from>.vmdk <to>.vdi

Generating a VDI out of the box with -f virtualbox doesn't appear to be working currently with the default config.

Inbound Ports: 22556 (core), 42069 (Dogenet)

Depending on what Pups you install you will likely want to forward inbound connections. Installing Dogecoin Core Pup requires port 22556 and for Dogenet 42069, other Pups may also require inbound connection forwarding, depending on what they do.

Home routers

In most homes, computers connect to the Internet through a modem or a router, which is configured to block incoming connections to most ports. To forward ports, you will need to follow the following steps.

Please refer to your router’s manual for specific instructions.

  1. Access your router’s control panel using your internet browser. Usually, most routers have a control panel accessible at https://192.168.0.1 or at https://192.168.1.1. Sometimes, a sticker is placed on the bottom or the side of the router listing the IP.

  2. Login into the control panel of the router. You will need to use the username and password provided by the router manufacturer. Sometimes, a sticker is placed on the bottom or the side of the router revealing the admin password.

  3. In the router’s control panel, assign a static IP to your Dogebox. This is normally done in the Dynamic Host Configuration Protocol (DHCP) page.

  4. In the router’s control panel, configure port forwarding: forward all inbound traffic from 22556 (core) and 42069 (Dogenet) to the same ports at the static IP you assigned to your Dogebox.

Installing PUPs

Pups are the lifeblood of the Dogebox, these are packaged services that the Dogebox runs inside an isolated container, they can depend on other Pups such as Dogecoin Core or GigaWallet, and thus build up a functional Dogecoin ecosystem that can provide online shopping, tipping, new wallets or anything else that interacts with the Dogecoin Blockchain.

Managing Pups

Explore - The Pup Store

Clicking the 'Explore' link in the nav will take you to the 'Pup Store' where all available Pups can be found.

⚠️ Note: To start with you will only see a few Pups provided by the Dogecoin Foundation supported 'Pup Source', such as Dogecoin Core, Dogecoin GigaWallet, Dogenet and a few others. More Pups can be added to the store by adding new 'Pup Sources' (see below).

Pup Store

Pup Sources - Where do pups come from?

Dogebox is designed to let the community create and distribute Pups without any centralised group controlling a 'store' (hint: like Google or Apple!).

From the Pup Store you can 'manage sources', and paste in a URI to a different Pup source form the internet. This will be scanned and any pups found will be available in the Pup Store.

⚠️ Note: currently Sources are Git repositories that follow a particular format, however we are working on other Source types such as decentralised Radicle sources, http and others.

Pup Sources

Pup Installation

Clicking a pup from the Pup Store will let you install the Pup. Dogebox will prepare an isolated 'container' for your Pup to run in, and assign any resources that your Pup needs based on it's config.

⚠️ Note: This may take some time as Dogebox will download the source-code for the software and compile it on your Dogebox. Dogecoin Core may take 10 minutes or more depending on your hardware. Grab a cuppa and chill.

Pup Installation

Pup Management Screen

The pup management screen exists for every installed pup, and is the main control panel for interacting with the software. From here you can monitor the general Stats of the container, view any custom Mertrics or Logs, and launch the Pup's own UI (if it provides one!)

Pup Management Screen

Meeting Dependencies

Some pups depend on other pups, they do this via 'Interfaces' and 'Providers'. A pup that requires an interface provider will let you know by entering the Unmet Dependencies state.

At this point you will need to install or select a pup that 'provides' the required interface. Don't worry, there's a helpful dialog to get you through this step.

Pup Deps

Enabling / Disabling Pups

From the Pup management screen, you can use the 'Enabled' slider to enable or disable a pup.

⚠️ Note: this may take a little time as Dogebox is managing interconnected services related to this Pup, opening or closing firewall ports and updating it's internal routes.

Enable / Disable

Reading Logs

For the more technically minded, you can click the 'Logs' action under the Pup management screen to see the output of the Pup in realtime.

Reading Logs

DRE Development Environment

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/dogeorg/dogeboxd.git
  • DPanel - https://github.com/dogeorg/dpanel.git
  • DKM - https://github.com/dogeorg/dkm.git

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

Configure your Nix environment

As we're running a development environment, some things must be configured manually.

Import dogebox.nix

Edit /etc/nixos/configuration.nix. Towards the top of the file there should be an imports section.

Please modify it to conditionally include the dogebox.nix file that will live in $HOME/data/nix/dogebox.nix

For example, if your existing imports block looks like:

  imports =
    [
      "${modulesPath}/virtualisation/lxc-container.nix"
      ./lxd.nix
    ];

Please change it to:

  imports =
    [
      "${modulesPath}/virtualisation/lxc-container.nix"
      ./lxd.nix
    ] ++ lib.optionals (builtins.pathExists "/home/$USER/data/nix/dogebox.nix") [
      /home/$USER/data/nix/dogebox.nix
    ];

Where $USER is the user you have inside your NixOS VM.

Add required packages

Edit /etc/nixos/configuration.nix. Inside the main { ... } block, please add:

environment.systemPackages = [ pkgs.git pkgs.vim ];

nb. Vim is not required, but lots of people get annoying that it is not available :)

Add required security wrappers

Edit /etc/nixos/configuration.nix. Inside the main { ... } block, please add:

security.wrappers.dbx = {
  source = "/home/$USER/dogeboxd/build/dbx";
  owner = "$USER";
  group = "users";
};

security.wrappers.dogeboxd = {
  source = "/home/$USER/dogeboxd/build/dogeboxd";
  capabilities = "cap_net_bind_service=+ep";
  owner = "$USER";
  group = "users";
};

security.wrappers._dbxroot = {
  source = "/home/$USER/dogeboxd/build/_dbxroot";
  owner = "root";
  group = "root";
  setuid = true;
};

Please note: Please fix these paths, they assume you have cloned dogeboxd into the users home directory. If you cloned them elsewhere, update the paths. Please note: There are multiple instances of $USER that need replacing, please update all of them.

Rebuild

Once you've added the above, you can rebuild your VM to ensure it's in a proper state to execute everything.

Please run: sudo nixos-rebuild switch. Assuming this succeeds, you're ready to rock and roll.

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 shell.nix which provides 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-shell
make dev
Starting dkm
cd dkm
nix-shell
make dev

dogeboxd should now be listening on http://127.0.0.1:3000 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.