init projectmycelium
This commit is contained in:
mik-tf
230
docs/ops/method/current/automated-deployment.md
Normal file
230
docs/ops/method/current/automated-deployment.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user