{"id":26926074,"url":"https://github.com/mlorentedev/mlorente.dev","last_synced_at":"2025-04-02T03:30:17.526Z","repository":{"id":260867844,"uuid":"882537199","full_name":"mlorentedev/mlorente.dev","owner":"mlorentedev","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-28T03:16:38.000Z","size":9885,"stargazers_count":0,"open_issues_count":30,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-28T03:23:04.442Z","etag":null,"topics":["astro","docker-compose","golang"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlorentedev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-03T03:26:12.000Z","updated_at":"2025-03-28T02:33:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"c7f75c95-417e-4ee6-ae6e-d3a2bf1655db","html_url":"https://github.com/mlorentedev/mlorente.dev","commit_stats":null,"previous_names":["mlorentedev/astrowind"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlorentedev%2Fmlorente.dev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlorentedev%2Fmlorente.dev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlorentedev%2Fmlorente.dev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlorentedev%2Fmlorente.dev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlorentedev","download_url":"https://codeload.github.com/mlorentedev/mlorente.dev/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246750678,"owners_count":20827766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astro","docker-compose","golang"],"created_at":"2025-04-02T03:30:17.048Z","updated_at":"2025-04-02T03:30:17.491Z","avatar_url":"https://github.com/mlorentedev.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mlorente.dev\n\nThis is my minimal website [mlorente.dev](https://mlorente.dev) with modern architecture based in containers.\n\nThis project demonstrates a production-ready microservices approach using containers, seamlessly integrating a static frontend with a dynamic backend. It showcases best practices for development, deployment, and maintenance of a modern web application with minimal JavaScript.\n\n## Technology Stack\n\n- **Frontend**:\n\n  - [Astro](https://astro.build) for static site generation and server-side rendering\n  - [HTMX](https://htmx.org) for dynamic content without complex JavaScript\n  - [TailwindCSS](https://tailwindcss.com) for utility-first styling\n  - Minimal client-side JavaScript for enhanced performance\n\n- **Backend**:\n  - [Go](https://golang.org) for high-performance API services\n  - Clean architecture with clear separation of concerns\n  - RESTful API design principles\n  - Structured logging and error handling\n\n- **Infrastructure**:\n  - [Docker](https://www.docker.com) for containerization and consistent environments\n  - [Docker Compose](https://docs.docker.com/compose) for service orchestration\n  - [GitHub Actions](https://github.com/features/actions) for CI/CD automation\n  - [Nginx](https://nginx.org) as reverse proxy and SSL termination\n  - [Let's Encrypt](https://letsencrypt.org) for SSL certificates\n\n## Project Structure\n\n```text\n|── .github/workflows/      # CI/CD workflows\n├── backend/                # Go backend services\n│   ├── cmd/server/         # Application entry point\n│   ├── internal/           # Private application code\n│   └── pkg/                # Shared packages\n├── docker/                 # Docker configuration files\n├── frontend/               # Astro application\n│   ├── public/             # Static assets\n│   └── src/                # Source code\n│       ├── components/     # UI components\n│       ├── content/        # Markdown/MDX content\n│       ├── layouts/        # Page templates\n│       └── pages/          # Route definitions\n├── scripts/                # Utility scripts\n└── .env.dev               # Development environment variables\n```\n\n## Getting Started\n\n### Requirements\n\n- Node.js 18.0.0+\n- npm 6.0.0+\n- Docker and Docker Compose (for containerized development)\n- Go 1.18+ (for backend development)\n\n### Initial Setup\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/username/mlorente.dev.git\n   cd mlorente.dev\n   ```\n\n2. Setup development environment:\n\n   ```bash\n   # Configure development environment\n   ./scripts/setup-env.sh\n   ```\n\n### Development Workflow\n\n#### Containerized Development (Recommended)\n\n```bash\n# Build and start services\ndocker compose -f docker-compose.dev.yml build #--no-cache\ndocker compose -f docker-compose.dev.yml up --force-recreate\n\n# View logs\ndocker compose -f docker-compose.dev.yml logs -f [service_name]\n\n# Stop all services\ndocker compose -f docker-compose.dev.yml down\n```\n\nContainerized development provides:\n\n- Frontend at \u003chttp://localhost:3000\u003e\n- Backend at \u003chttp://localhost:8080\u003e\n- Hot reloading for both frontend and backend\n- Consistent logging and error handling\n\n#### Individual Component Development\n\n**Frontend**:\n\n```bash\ncd frontend\nnpm install\nnpm run dev\n```\n\n**Backend**:\n\n```bash\ncd backend\ngo mod download\ngo mod tidy\ngo run cmd/server/main.go\n```\n\nFor hot reloading with Go:\n\n```bash\ngo install github.com/air-verse/air@latest\nexport PATH=$(go env GOPATH)/bin:$PATH\nair\n```\n\n## API Endpoints\n\nThe backend exposes these RESTful endpoints to support the frontend application:\n\n- **`/api/subscribe`**:\n  - **Method**: POST\n  - **Purpose**: Register a new email for newsletter subscription\n  - **Request Body**: `{ \"email\": \"user@example.com\", \"tags\": [\"tag1\", \"tag2\"], \"utmSource\": \"source\" }`\n  - **Response**: Subscription confirmation with subscriber ID\n\n- **`/api/unsubscribe`**:\n  - **Methods**: POST, GET\n  - **Purpose**: Remove an email from newsletter subscriptions\n  - **Request Body** (POST): `{ \"email\": \"user@example.com\" }`\n  - **Query Params** (GET): `?email=user@example.com`\n  - **Response**: Confirmation of unsubscription\n\n- **`/api/lead-magnet`**:\n  - **Method**: POST\n  - **Purpose**: Subscribe user and send a resource (lead magnet)\n  - **Request Body**: `{ \"email\": \"user@example.com\", \"resourceId\": \"id\", \"fileId\": \"file\", \"tags\": [\"tag1\"] }`\n  - **Response**: Confirmation of subscription and resource delivery\n\n- **`/api/resource-email`**:\n  - **Method**: POST\n  - **Purpose**: Send an email with resource to existing subscriber\n  - **Request Body**: `{ \"email\": \"user@example.com\", \"resourceId\": \"id\", \"resourceLink\": \"url\" }`\n  - **Response**: Confirmation of email delivery\n\nThese endpoints utilize HTMX-compatible responses, allowing for seamless frontend integration without complex JavaScript.\n\n## Deployment\n\n### CI/CD Pipeline\n\nThe project uses GitHub Actions for continuous integration and deployment with separate workflows for frontend and backend:\n\n#### Frontend CI Workflow\n\n- **Trigger**: Changes to `/frontend` or workflow files\n- **Steps**:\n  1. Checkout code\n  2. Setup Node.js environment\n  3. Install dependencies\n  4. Run linting and type checking\n  5. Execute tests\n  6. Build the application\n  7. Create and push Docker image\n\n#### Backend CI Workflow\n\n- **Trigger**: Changes to `/backend` or workflow files\n- **Steps**:\n  1. Checkout code\n  2. Setup Go environment\n  3. Install dependencies\n  4. Run `go vet` for static analysis\n  5. Execute tests\n  6. Build the application\n  7. Create and push Docker image\n\n#### Deploy Workflow\n\n- **Trigger**:\n  - Completion of CI workflows\n  - Manual trigger from GitHub UI\n  - Repository dispatch event\n- **Environment Selection**:\n  - `master` branch → Production (`mlorente.dev`)\n  - `feature/*` or `hotfix/*` branches → Staging (`staging.mlorente.dev`)\n- **Steps**:\n  1. Connect to server via SSH\n  2. Update configuration\n  3. Pull latest Docker images\n  4. Apply database migrations (if needed)\n  5. Restart services\n  6. Run health checks\n\n### Branch Strategy\n\n- **`master`**: Production-ready code, deployed to production\n- **`develop`**: Integration branch for feature development\n- **`feature/*`**: Isolated feature development, merged to develop\n- **`hotfix/*`**: Urgent fixes applied directly to master and develop\n\n### Deployment Environments\n\n| Environment | URL | Purpose | Access |\n|-------------|-----|---------|--------|\n| Production | mlorente.dev | Live site | Public |\n| Staging | staging.mlorente.dev | Pre-release testing | Private |\n\n### Manual Deployment\n\nFor situations where CI/CD is not suitable, manual deployment is possible:\n\n```bash\n# Deploy to production\n./scripts/deploy.sh production\n\n# Deploy to staging\n./scripts/deploy.sh staging\n\n# Direct deployment on production server\ncd /opt/mlorente\ndocker-compose pull\ndocker-compose up -d\n```\n\n### Deployment Verification\n\nAfter deployment, automatic health checks verify the application status:\n\n```bash\n# Check application health\n./scripts/health-check.sh production\n\n# View deployment logs\n./scripts/deployment-logs.sh production\n```\n\n## Infrastructure\n\n### Hosting Environment\n\nThe application is hosted on Hetzner Cloud with the following specifications:\n\n#### Production Server\n\n- **Hostname**: `mlorente.dev`\n- **Server Type**: Hetzner CX41 (4 vCPU, 16GB RAM)\n- **Location**: Falkenstein, Germany (EU-central)\n- **Operating System**: Ubuntu 22.04 LTS\n- **Firewall**: UFW with restricted access\n- **Monitoring**: Node Exporter + Prometheus\n\n#### Staging Server\n\n- **Hostname**: `staging.mlorente.dev`\n- **Server Type**: Hetzner CX21 (2 vCPU, 4GB RAM)\n- **Location**: Falkenstein, Germany (EU-central)\n- **Operating System**: Ubuntu 22.04 LTS\n- **Firewall**: UFW with restricted access\n\n### Server Setup\n\nEach server is configured using the `setup-server.sh` script, which:\n\n1. Updates the system\n2. Installs Docker and Docker Compose\n3. Configures firewall rules\n4. Sets up fail2ban for SSH protection\n5. Creates a non-root deployment user\n6. Configures automatic security updates\n7. Sets up Let's Encrypt certificates\n\n### Docker Images\n\nDocker images are stored on DockerHub with the following versioning scheme:\n\n#### Frontend Images\n\n- `mlorentedev/mlorente-frontend:latest` - Production version (master branch)\n- `mlorentedev/mlorente-frontend:develop` - Development version\n- `mlorentedev/mlorente-frontend:[commit-hash]` - Specific commit version\n- `mlorentedev/mlorente-frontend:feature-*` - Feature branch versions\n\n#### Backend Images\n\n- `mlorentedev/mlorente-backend:latest` - Production version (master branch)\n- `mlorentedev/mlorente-backend:develop` - Development version\n- `mlorentedev/mlorente-backend:[commit-hash]` - Specific commit version\n- `mlorentedev/mlorente-backend:feature-*` - Feature branch versions\n\n### Network Architecture\n\n```text\n                   ┌─────────────┐\n                   │    Nginx    │\n                   │Reverse Proxy│\n                   └──────┬──────┘\n                          │\n                          ▼\n          ┌───────────────┴───────────────┐\n          │                               │\n┌─────────▼──────────┐       ┌────────────▼─────────┐\n│                    │       │                      │\n│  Frontend (Astro)  │       │   Backend (Go API)   │\n│                    │       │                      │\n└────────────────────┘       └──────────────────────┘\n```\n\nAll services run as Docker containers orchestrated with Docker Compose, with Nginx serving as the entry point and handling SSL termination.\n\n## Troubleshooting\n\n### Common Issues and Solutions\n\n#### Application Not Responding\n\nIf the application is not responding, first check the container status:\n\n```bash\ndocker-compose ps\n```\n\nLook for containers in an unhealthy state or containers that have restarted multiple times. If needed, restart services:\n\n```bash\ndocker-compose restart\n```\n\n#### Frontend Errors\n\nFor issues with the frontend application:\n\n```bash\ndocker-compose logs frontend\n```\n\nCommon frontend issues include:\n\n- Missing environment variables\n- Build failures due to syntax errors\n- Static asset loading problems\n- CORS issues when communicating with the backend\n\n#### Backend Errors\n\nFor backend service issues:\n\n```bash\ndocker-compose logs backend\n```\n\nCommon backend issues include:\n\n- Database connection failures\n- API validation errors\n- External service integration problems\n- Resource constraints (memory/CPU)\n\n#### SSL Certificate Issues\n\nIf experiencing SSL errors:\n\n```bash\n# Check certificate status\ndocker-compose exec nginx openssl x509 -in /etc/letsencrypt/live/mlorente.dev/fullchain.pem -text -noout\n\n# Restart certbot to attempt renewal\ndocker-compose restart certbot\n```\n\n#### Deployment Failures\n\nIf a deployment fails or introduces issues:\n\n```bash\n# List available versions\n./scripts/rollback.sh production list\n\n# Roll back to a specific version\n./scripts/rollback.sh production v1.2.3\n```\n\n#### Environment Variable Problems\n\nIf environment variables are missing or incorrect:\n\n```bash\n# Update environment variables\n./scripts/update-env.sh production\n```\n\n## Advanced Operations\n\nThe project includes utility scripts for maintenance and operational tasks:\n\n### Performance Testing\n\nTest the performance of individual endpoints or the entire application:\n\n```bash\n# Test performance of all endpoints in production\n./scripts/monitor-performance.sh production\n\n# Test specific endpoint with 1000 requests and 50 concurrent users\n./scripts/monitor-performance.sh production /api/subscribe 1000 50\n\n# Compare performance between environments\n./scripts/monitor-performance.sh compare production staging\n```\n\nThe performance testing script uses `wrk` under the hood and provides metrics on:\n\n- Requests per second\n- Average response time\n- P95/P99 response times\n- Error rates\n\n### Security Verification\n\nVerify security configuration and identify potential vulnerabilities:\n\n```bash\n# Comprehensive security scan of production environment\n./scripts/monitor-security.sh production\n\n# Check specific aspect (ssl, headers, firewall, etc.)\n./scripts/monitor-security.sh production ssl\n\n# Generate a detailed security report\n./scripts/monitor-security.sh production --report\n```\n\nThe security check includes:\n\n- SSL configuration and certificate validation\n- HTTP security headers\n- Firewall rule verification\n- Open port scanning\n- Docker configuration best practices\n\n### Log Analysis\n\nAnalyze application logs to identify issues or patterns:\n\n```bash\n# Analyze all service logs in production\n./scripts/monitor-logs.sh production\n\n# Analyze specific service logs\n./scripts/monitor-logs.sh production nginx\n\n# Focus on errors only\n./scripts/monitor-logs.sh production --errors-only\n\n# Analyze logs within a time period\n./scripts/monitor-logs.sh production --since \"2023-01-01\" --until \"2023-01-02\"\n```\n\nThe log analysis provides:\n\n- Error frequency and patterns\n- Request path analysis\n- Performance bottlenecks\n- User behavior insights\n- Anomaly detection\n\n## Additional Resources\n\n- [CONTRIBUTING.md](CONTRIBUTING.md): Contribution guidelines\n- [LICENSE](LICENSE): MIT License information\n- [scripts/README.md](scripts/README.md): Documentation for utility scripts\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlorentedev%2Fmlorente.dev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlorentedev%2Fmlorente.dev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlorentedev%2Fmlorente.dev/lists"}