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.
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.
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
- Install directly on a FriendlyElec T6 ARM
- Install directly on any x86 computer as the host OS
- Install images for various Virtual Machines
- How to build the above images from source
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
-
Download Virtualbox, or another OVA compatible VM launcher.
-
Import the OVA image by selecting the file you downloaded from the latest release.
- Ensure the VM has sufficient RAM for the software you plan to run on the Dogebox.
- Once imported, click 'Settings' and configure your network to use 'bridged mode'.
- Launch the VM. This may take up to 10 minutes depending on your internet connection, to configure itself initially, grab a cuppa.
- Login with username:
shibe
and password:suchpass
, then runip 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
- 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
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.
-
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.
-
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.
-
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.
-
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.
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 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 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 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!)
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.
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.
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.
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
orrestart
, the dogeboxd process willexit
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
andDKM
is written to~/data
. Deleting this directory will reset your state.