Sync .cursor from detections

2026-04-22 22:06:39 +00:00 · 2026-04-12 05:05:11 +03:00
parent fddf1b8706
commit 09117f90b5
108 changed files with 11844 additions and 15 deletions
@@ -0,0 +1,114 @@
+# Deployment Scripts Documentation Template
+
+Save as `_docs/04_deploy/deploy_scripts.md`.
+
+---
+
+```markdown
+# [System Name] — Deployment Scripts
+
+## Overview
+
+| Script | Purpose | Location |
+|--------|---------|----------|
+| `deploy.sh` | Main deployment orchestrator | `scripts/deploy.sh` |
+| `pull-images.sh` | Pull Docker images from registry | `scripts/pull-images.sh` |
+| `start-services.sh` | Start all services | `scripts/start-services.sh` |
+| `stop-services.sh` | Graceful shutdown | `scripts/stop-services.sh` |
+| `health-check.sh` | Verify deployment health | `scripts/health-check.sh` |
+
+## Prerequisites
+
+- Docker and Docker Compose installed on target machine
+- SSH access to target machine (configured via `DEPLOY_HOST`)
+- Container registry credentials configured
+- `.env` file with required environment variables (see `.env.example`)
+
+## Environment Variables
+
+All scripts source `.env` from the project root or accept variables from the environment.
+
+| Variable | Required By | Purpose |
+|----------|------------|---------|
+| `DEPLOY_HOST` | All (remote mode) | SSH target for remote deployment |
+| `REGISTRY_URL` | `pull-images.sh` | Container registry URL |
+| `REGISTRY_USER` | `pull-images.sh` | Registry authentication |
+| `REGISTRY_PASS` | `pull-images.sh` | Registry authentication |
+| `IMAGE_TAG` | `pull-images.sh`, `start-services.sh` | Image version to deploy (default: latest git SHA) |
+| [add project-specific variables] | | |
+
+## Script Details
+
+### deploy.sh
+
+Main orchestrator that runs the full deployment flow.
+
+**Usage**:
+- `./scripts/deploy.sh` — Deploy latest version
+- `./scripts/deploy.sh --rollback` — Rollback to previous version
+- `./scripts/deploy.sh --help` — Show usage
+
+**Flow**:
+1. Validate required environment variables
+2. Call `pull-images.sh`
+3. Call `stop-services.sh`
+4. Call `start-services.sh`
+5. Call `health-check.sh`
+6. Report success or failure
+
+**Rollback**: When `--rollback` is passed, reads the previous image tags saved by `stop-services.sh` and redeploys those versions.
+
+### pull-images.sh
+
+**Usage**: `./scripts/pull-images.sh [--help]`
+
+**Steps**:
+1. Authenticate with container registry (`REGISTRY_URL`)
+2. Pull all required images with specified `IMAGE_TAG`
+3. Verify image integrity via digest check
+4. Report pull results per image
+
+### start-services.sh
+
+**Usage**: `./scripts/start-services.sh [--help]`
+
+**Steps**:
+1. Run `docker compose up -d` with the correct env file
+2. Configure networks and volumes
+3. Wait for all containers to report healthy state
+4. Report startup status per service
+
+### stop-services.sh
+
+**Usage**: `./scripts/stop-services.sh [--help]`
+
+**Steps**:
+1. Save current image tags to `previous_tags.env` (for rollback)
+2. Stop services with graceful shutdown period (30s)
+3. Clean up orphaned containers and networks
+
+### health-check.sh
+
+**Usage**: `./scripts/health-check.sh [--help]`
+
+**Checks**:
+
+| Service | Endpoint | Expected |
+|---------|----------|----------|
+| [Component 1] | `http://localhost:[port]/health/live` | HTTP 200 |
+| [Component 2] | `http://localhost:[port]/health/ready` | HTTP 200 |
+| [add all services] | | |
+
+**Exit codes**:
+- `0` — All services healthy
+- `1` — One or more services unhealthy
+
+## Common Script Properties
+
+All scripts:
+- Use `#!/bin/bash` with `set -euo pipefail`
+- Support `--help` flag for usage information
+- Source `.env` from project root if present
+- Are idempotent where possible
+- Support remote execution via SSH when `DEPLOY_HOST` is set
+```