# 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: ```bash cp .env.deploy.example .env.deploy ``` 2. Edit `.env.deploy` with your Gitea credentials: ```bash GITEA_USER=your_username GITEA_TOKEN=your_personal_access_token ``` 3. Setup development environment: ```bash make setup-dev ``` ## Available Commands ### First-Time Setup Commands #### Setup Development Environment ```bash 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 ```bash 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 ```bash make setup ``` Sets up both development and production environments in sequence. ### Regular Update Commands #### Update Development Environment ```bash 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 ```bash 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 ```bash make status ``` Shows the status of both marketplace services. #### View Service Logs ```bash make logs ``` Shows logs from both development and production services. ### Local Development Commands #### Build and Run Locally ```bash make build ``` Builds and runs the application locally (checks/generates `.env` file automatically). #### Generate Secret Key ```bash make key ``` Generates a new `SECRET_KEY` in the `.env` file. #### Get Help ```bash 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`: ```bash ssh root@info.ourworld.tf 'echo "Connection successful"' ``` ### Service Not Starting Check service logs: ```bash make logs ``` Or check directly on the server: ```bash 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: ```bash 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 ```bash 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 ```bash 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: ```bash 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`