projectmycelium/docs/ops/method/current/deployment.md

Basic Deployment Guide for Project Mycelium

This guide provides a simplified approach to deploying the Project Mycelium on a server, using cargo run directly.

🚀 For automated deployment, see Automated Deployment Guide

We show the steps for the main branch, for development branch, simply add _dev, -dev accordingly and checkout into development.

Prerequisites

• Linux server with:
  • Git installed
  • Rust toolchain installed
  • Caddy web server installed
  • zinit service manager installed
  • Root or access

Step 1: Clone the Repository

We'll clone the repository to a structured directory path:

# Create directory structure
mkdir -p /root/code/git.ourworld.tf/tfgrid/prod
cd /root/code/git.ourworld.tf/tfgrid/prod

# Clone the repository
git clone https://git.ourworld.tf/tfgrid/projectmycelium
cd projectmycelium
git checkout main

Step 2: Create a zinit Service

Create a zinit service to run and manage the application:

1. First create the service script:

mkdir -p /etc/zinit/cmds
nano /etc/zinit/cmds/projectmycelium.sh

Add the following content:

#!/bin/bash
cd /root/code/git.ourworld.tf/tfgrid/prod/projectmycelium
git checkout main
exec /root/.cargo/bin/cargo run --release --bin projectmycelium -- --port 9989

Make the script executable:

chmod +x /etc/zinit/cmds/projectmycelium-prod.sh

2. Create the zinit service definition:

nano /etc/zinit/projectmycelium-prod.yaml

Add the following content:

exec: "/bin/bash -c /etc/zinit/cmds/projectmycelium-prod.sh"

Step 3: Configure Caddy

Create or update your Caddyfile to serve the application:

# Edit the Caddyfile
nano /root/code/github/despiegk/env_web/ourworld/ovh1_web_current/caddy/Caddyfile

• Add the Caddy file in Caddyfile

  import projectmycelium.caddy
  

• Create projectmycelium-prod.caddy then enter the following. Adjust your domain as needed.

projectmycelium.org {
    reverse_proxy localhost:9989 {
        header_up Host {host}
        header_up X-Real-IP {remote}
        header_up X-Forwarded-Proto {scheme}
    }
}

Step 4: Start Services with zinit

• Monitor the zinit service

zinit monitor projectmycelium-prod

• Start the service

# Start the marketplace service
zinit start projectmycelium-prod

# Restart Caddy to load new configuration
zinit restart caddy

Automated Deployment with Makefile

For easier deployment, you can use the provided Makefile targets with separate dev and prod environments:

First-Time Setup

1. Set up deployment credentials:

# Create deployment credentials file
cp .env.deploy.example .env.deploy

# Edit deployment credentials
nano .env.deploy

# Add your Gitea credentials:
GITEA_USER=your_username
GITEA_TOKEN=your_personal_access_token

2. Deploy to server (choose one):

Option A: Setup development only:

make setup-dev

Option B: Setup production only:

make setup-prod

Option C: Setup both dev and prod:

make setup

Clean Environment Structure

The deployment system uses industry-standard environment separation:

/root/code/git.ourworld.tf/tfgrid/
├── dev/projectmycelium/     # Development branch (port 9998)
└── prod/projectmycelium/    # Production branch (port 9989)

Benefits:

• ✅ No build conflicts: Each environment has its own build cache
• ✅ Independent deployments: Dev and prod can be updated separately
• ✅ Parallel compilation: Both can build simultaneously
• ✅ Clean separation: Different branches, ports, and domains

What each setup does:

setup-dev:

• Sets up development environment only
• Clones to dev/projectmycelium/
• Uses development branch
• Runs on port 9998 (dev.projectmycelium.org)

setup-prod:

• Sets up production environment only
• Clones to prod/projectmycelium/
• Uses main branch
• Runs on port 9989 (projectmycelium.org)
• Restarts Caddy for production

setup (both):

• Runs both dev and prod setups
• Complete environment setup

Regular Deployments

Simple Updates (recommended):

# Update development branch (just git pull + restart)
make update-dev

# Update production branch (just git pull + restart)
make update-prod

What happens:

• SSH to server
• Navigate to repository directory
• Git pull latest changes
• Restart the service

Monitoring:

# Check service status
make status

# View service logs
make logs

# Get help with all commands
make help

Manual Alternative:

# Development
ssh root@info.ourworld.tf
cd /root/code/git.ourworld.tf/tfgrid/dev/projectmycelium
git checkout development && git pull
zinit restart projectmycelium-dev

# Production
ssh root@info.ourworld.tf
cd /root/code/git.ourworld.tf/tfgrid/prod/projectmycelium
git checkout main && git pull
zinit restart projectmycelium-prod

Creating a Gitea Personal Access Token

1. Go to https://git.ourworld.tf/user/settings/applications
2. Click "Generate New Token"
3. Give it a descriptive name (e.g., "Project Mycelium Deployment")
4. Select minimal permissions: repository read access only
5. Copy the generated token and add it to your local .env file as GITEA_TOKEN

Environment File Structure

Two separate environment files for clean separation:

Local .env.deploy (deployment credentials only):

# Gitea credentials for deployment
GITEA_USER=your_username
GITEA_TOKEN=your_personal_access_token

Server .env (application secrets, auto-generated):

# Application secret (automatically generated on server)
SECRET_KEY=auto_generated_secret_key

Clean Separation:

• Deployment credentials: Only in .env.deploy, used for git authentication
• Application secrets: Generated automatically on server in cloned repo
• No mixing: Deployment and application concerns completely separated

Updating the Application

To update the application after making changes:

# Go to the repository directory
cd /root/code/git.ourworld.tf/tfgrid/projectmycelium

# Pull the latest changes
git checkout main
git pull

# Restart the application service
zinit restart projectmycelium-prod

Monitoring the Application

You can monitor the application status with these commands:

# Check if the application is running
zinit list

# View application logs
zinit log projectmycelium-prod

# Monitor logs in real-time
tail -f /var/log/zinit/projectmycelium-prod.log

Troubleshooting

Application Not Starting

Check for errors in the application logs:

zinit log projectmycelium-prod

Connection Refused

Make sure the application is running and listening on the correct port:

ss -tuln | grep 9989