development_toolbox

What this is

Deploy any Docker Compose application to a ThreeFold Grid VM with a single command. This toolbox uses OpenTofu (or Terraform) to provision an Ubuntu 24.04 VM with public IPv4 and Mycelium connectivity, then runs a customizable setup script to install Docker, clone your application, and start services.

What this repository contains

development_toolbox/
├── Makefile                          # Orchestrator
├── app.env.example                   # App config template
├── .gitignore
├── tf/
│   ├── main.tf                       # VM + network + public IP + mycelium
│   ├── variables.tf                  # Input variables
│   ├── outputs.tf                    # IP addresses, SSH commands
│   └── credentials.auto.tfvars.example
└── scripts/
    └── setup.sh                      # VM provisioning (customize this)

Role in the stack

development_toolbox is a deployment automation tool for the ThreeFold Grid. It provisions VMs with Mycelium overlay network connectivity, pre-installs Docker and Docker Compose, and sets up a systemd service for auto-restart on reboot. It is used to deploy applications that run on MyceliumOS nodes or ThreeFold Grid VMs and need to be reachable via both public IPv4 and the Mycelium overlay network.

Relation to ThreeFold

This technology is used within the ThreeFold ecosystem and was first deployed on the ThreeFold Grid. The component itself is designed as reusable infrastructure technology and should be understood by its technical function first, independent of any specific deployment.

Ownership

This repository is owned and maintained by TF-Tech NV, a Belgian company responsible for the development and maintenance of this technology.

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.

---

Quick start

# 1. Configure credentials
cp tf/credentials.auto.tfvars.example tf/credentials.auto.tfvars
# Edit with your ThreeFold Grid mnemonic

# 2. Configure your app
cp app.env.example app.env
# Edit with your domain, git repo, etc.

# 3. Customize scripts/setup.sh for your app
#    (Docker Compose commands, env vars, Caddyfile, etc.)

# 4. Deploy
make all

Makefile targets

Target	Description
make all	Full deploy: init + deploy + setup + dns + test + info
make init	Initialize OpenTofu providers
make deploy	Provision VM on the grid
make setup	Install Docker + app on the VM
make destroy	Tear down all infrastructure
make clean	Remove generated and cached files
make dns	Set Cloudflare A record (auto-discovers zone ID)
make test	Verify services are responding
make info	Show endpoints and connection info
make ssh	SSH into the VM

Customization

The main file to customize is scripts/setup.sh. It has numbered sections:

1. Load config - reads app.env, derives domain
2. Install packages - base Ubuntu packages
3. Install Docker - with fuse-overlayfs (required on ThreeFold Grid)
4. Clone app - git clone or pull your repo
5. Generate .env - Docker Compose environment
6. Caddyfile - reverse proxy config (commented out by default)
7. Docker login - for private registries
8. Start services - docker compose up
9. Systemd service - auto-restart
10. Health check - verify app is responding

For a typical app, you'll edit sections 4-6 and possibly 8.

Prerequisites

• OpenTofu (or Terraform) installed locally
• ThreeFold Grid account with funded wallet
• SSH key pair (~/.ssh/id_ed25519.pub by default)
• curl, jq for DNS and test targets

Pinning to a specific node

By default, the grid scheduler auto-selects a node. To pin:

# tf/credentials.auto.tfvars
node_id = 8

DNS

The make dns target manages Cloudflare A records. Set CLOUDFLARE_API_TOKEN in app.env. The zone ID is auto-discovered from your domain.

Examples

To deploy a WordPress site, you would:

1. Set GIT_REPO to your repo containing docker-compose.yml with WordPress + MariaDB
2. Customize setup.sh section 5 to generate the WordPress .env
3. Uncomment section 6 to generate a Caddyfile
4. make all