230 lines
6.0 KiB
Markdown
230 lines
6.0 KiB
Markdown
# 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` |