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

Automated Deployment Guide

This guide explains how to use the automated deployment system for the Project Mycelium.

Prerequisites

• SSH access to root@info.ourworld.tf (passwordless SSH key setup recommended)
• Git repository with main and development branches
• Gitea credentials for deployment (username and personal access token)
• .env.deploy file configured with your Gitea credentials

Quick Start

1. Copy the deployment environment template:

   cp .env.deploy.example .env.deploy
   

2. Edit .env.deploy with your Gitea credentials:

   GITEA_USER=your_username
   GITEA_TOKEN=your_personal_access_token
   

3. Setup development environment:

   make setup-dev
   

Available Commands

First-Time Setup Commands

Setup Development Environment

make setup-dev

This will:

1. Validate .env.deploy file exists and has proper credentials
2. Copy development deployment script to server
3. Copy development service configuration
4. Copy deployment credentials to server
5. Setup monitoring for the development service
6. Start the tf-marketplace-dev service

Setup Production Environment

make setup-prod

This will:

1. Validate .env.deploy file exists and has proper credentials
2. Copy production deployment script to server
3. Copy production service configuration
4. Copy deployment credentials to server
5. Setup monitoring for the production service
6. Start the tf-marketplace-prod service
7. Restart Caddy to load configurations

Setup Both Environments

make setup

Sets up both development and production environments in sequence.

Regular Update Commands

Update Development Environment

make update-dev

This will:

1. SSH to the server
2. Navigate to development repository path
3. Checkout the development branch
4. Pull latest changes
5. Restart the tf-marketplace-dev service

Update Production Environment

make update-prod

This will:

1. SSH to the server
2. Navigate to production repository path
3. Checkout the main branch
4. Pull latest changes
5. Restart the tf-marketplace-prod service

Monitoring Commands

Check Service Status

make status

Shows the status of both marketplace services.

View Service Logs

make logs

Shows logs from both development and production services.

Local Development Commands

Build and Run Locally

make build

Builds and runs the application locally (checks/generates .env file automatically).

Generate Secret Key

make key

Generates a new SECRET_KEY in the .env file.

Get Help

make help

Shows all available commands with descriptions.

Deployment Workflow

Initial Setup Workflow

1. Copy .env.deploy.example to .env.deploy
2. Edit .env.deploy with your Gitea credentials
3. Run make setup-dev for development environment
4. Run make setup-prod for production environment (or make setup for both)

Development Workflow

1. Make changes in your local development branch
2. Push changes to development branch in gitea
3. Run make update-dev to deploy to development environment

Production Workflow

1. Create PR from development to main in gitea
2. Review and merge the PR
3. Run make update-prod to deploy to production environment

Server Configuration

The deployment assumes the following server setup:

• Development Repository Path: /root/code/git.ourworld.tf/tfgrid_research/dev/projectmycelium
• Production Repository Path: /root/code/git.ourworld.tf/tfgrid_research/prod/projectmycelium
• Development Service: tf-marketplace-dev
• Production Service: tf-marketplace-prod
• Zinit Configuration: Service configs stored in /etc/zinit/
• Deployment Scripts: Stored in /etc/zinit/cmds/

Troubleshooting

SSH Connection Issues

Ensure you have SSH key access to root@info.ourworld.tf:

ssh root@info.ourworld.tf 'echo "Connection successful"'

Service Not Starting

Check service logs:

make logs

Or check directly on the server:

ssh root@info.ourworld.tf 'zinit log tf-marketplace-prod'
ssh root@info.ourworld.tf 'zinit log tf-marketplace-dev'

Missing .env.deploy File

If you see errors about missing .env.deploy file:

1. Copy the template: cp .env.deploy.example .env.deploy
2. Edit the file with your Gitea credentials
3. Ensure GITEA_USER and GITEA_TOKEN are properly set

Invalid Gitea Credentials

If setup fails due to invalid credentials:

1. Verify your Gitea username and personal access token
2. Ensure the token has appropriate repository access permissions
3. Update .env.deploy with correct credentials

Service Status Issues

Check service status:

make status

This will show if services are running, stopped, or have errors.

Manual Deployment

If you need to deploy manually, the commands are:

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'

Environment Files

.env.deploy

Required for deployment setup. Contains Gitea credentials:

GITEA_USER=your_username
GITEA_TOKEN=your_personal_access_token

.env (Local Development)

Generated automatically by make build or make key. Contains:

• SECRET_KEY - Auto-generated secure key
• Other application configuration variables

Service Management

The deployment uses zinit for service management:

• Development Service: tf-marketplace-dev
• Production Service: tf-marketplace-prod
• Configuration Files:
  • /etc/zinit/tf-marketplace-dev.yaml
  • /etc/zinit/tf-marketplace-prod.yaml
• Deployment Scripts:
  • /etc/zinit/cmds/tf-marketplace-dev.sh
  • /etc/zinit/cmds/tf-marketplace-prod.sh