tfgrid_deploy

Deploy any Docker Compose application to a ThreeFold Grid VM with a single command.

What you get

• Ubuntu 24.04 VM with public IPv4 + Mycelium connectivity
• Docker + Docker Compose pre-installed
• Cloudflare DNS A record (optional)
• Systemd service for auto-restart on reboot
• SSH access via public IP or Mycelium

Quick start

# 1. Configure credentials
cp tf/credentials.auto.tfvars.example tf/credentials.auto.tfvars
# Edit with your TFGrid 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

Structure

tfgrid_deploy/
├── 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)

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 TFGrid)
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