init projectmycelium

docs/ops/method/current/deployment.md

@@ -0,0 +1,308 @@
+# 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
+```