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](./automated-deployment.md)**

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:

```bash
# Create directory structure
mkdir -p /root/code/git.ourworld.tf/tfgrid_research/
cd /root/code/git.ourworld.tf/tfgrid_research/

# Clone the repository
git clone https://git.ourworld.tf/tfgrid_research/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:

```bash 
mkdir -p /etc/zinit/cmds
nano /etc/zinit/cmds/tf-marketplace.sh
```

Add the following content:

```bash
#!/bin/bash
cd /root/code/git.ourworld.tf/tfgrid_research/projectmycelium
git checkout main
exec /root/.cargo/bin/cargo run --release --bin projectmycelium -- --port 9999
```

Make the script executable:

```bash
chmod +x /etc/zinit/cmds/tf-marketplace.sh
```

2. Create the zinit service definition:

```bash
nano /etc/zinit/tf-marketplace.yaml
```

Add the following content:

```yaml
exec: "/bin/bash -c /etc/zinit/cmds/tf-marketplace.sh"
```



## Step 3: Configure Caddy

Create or update your Caddyfile to serve the application:

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

- Add the Caddy file in Caddyfile
    ```
    import threefold_marketplace.caddy
    ```

- Create `threefold_marketplace.caddy` then enter the following. Adjust your domain as needed.

```
threefold.pro {
    reverse_proxy localhost:9999 {
        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 tf-marketplace-prod
```

- Start the service

```bash
# Start the marketplace service
zinit start tf-marketplace-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:**
```bash
# 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:**
```bash
make setup-dev
```

**Option B: Setup production only:**
```bash
make setup-prod
```

**Option C: Setup both dev and prod:**
```bash
make setup
```

### Clean Environment Structure

The deployment system uses industry-standard environment separation:

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

**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.threefold.pro)

**setup-prod:**
- Sets up production environment only
- Clones to `prod/projectmycelium/`
- Uses main branch
- Runs on port 9999 (threefold.pro)
- Restarts Caddy for production

**setup (both):**
- Runs both dev and prod setups
- Complete environment setup

### Regular Deployments

**Simple Updates (recommended):**
```bash
# 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:**
```bash
# Check service status
make status

# View service logs
make logs

# Get help with all commands
make help
```

**Manual Alternative:**
```bash
# Development
ssh root@info.ourworld.tf
cd /root/code/git.ourworld.tf/tfgrid_research/dev/projectmycelium
git checkout development && git pull
zinit restart tf-marketplace-dev

# Production
ssh root@info.ourworld.tf
cd /root/code/git.ourworld.tf/tfgrid_research/prod/projectmycelium
git checkout main && git pull
zinit restart tf-marketplace-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):**
```bash
# Gitea credentials for deployment
GITEA_USER=your_username
GITEA_TOKEN=your_personal_access_token
```

**Server `.env` (application secrets, auto-generated):**
```bash
# 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:

```bash
# Go to the repository directory
cd /root/code/git.ourworld.tf/tfgrid_research/projectmycelium

# Pull the latest changes
git checkout main
git pull

# Restart the application service
zinit restart tf-marketplace-prod
```

## Monitoring the Application

You can monitor the application status with these commands:

```bash
# Check if the application is running
zinit list

# View application logs
zinit log tf-marketplace-prod

# Monitor logs in real-time
tail -f /var/log/zinit/tf-marketplace-prod.log
```

## Troubleshooting

### Application Not Starting

Check for errors in the application logs:

```bash
zinit log tf-marketplace-prod
```

### Connection Refused

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

```bash
ss -tuln | grep 9999
```