Add build-test-run.sh, docker-compose.dev.yml for local development, update documentation, and add Cursor rules

.cursor/rules.json

@@ -0,0 +1,61 @@
+{
+  "version": 1,
+  "rules": [
+    {
+      "pattern": "**/*",
+      "rule": "project-structure.mdc"
+    },
+    {
+      "pattern": "**/docker/template/Dockerfile",
+      "rule": "dockerfiles.mdc"
+    },
+    {
+      "pattern": "**/docker/template/Dockerfile.production",
+      "rule": "dockerfiles.mdc"
+    },
+    {
+      "pattern": "**/docker-compose.dev.yml",
+      "rule": "docker-compose-files.mdc"
+    },
+    {
+      "pattern": "**/docker-compose.staging.yml",
+      "rule": "docker-compose-files.mdc"
+    },
+    {
+      "pattern": "**/docker-compose.production.yml",
+      "rule": "docker-compose-files.mdc"
+    },
+    {
+      "pattern": "**/docker-compose.test.yml",
+      "rule": "docker-compose-files.mdc"
+    },
+    {
+      "pattern": "**/stack.staging.yml",
+      "rule": "stack-files.mdc"
+    },
+    {
+      "pattern": "**/stack.production.yml",
+      "rule": "stack-files.mdc"
+    },
+    {
+      "pattern": "**/*.sh",
+      "rule": "scripts.mdc"
+    },
+    {
+      "pattern": "**/temp/**/*",
+      "rule": "temp-directory.mdc"
+    },
+    {
+      "pattern": "**/.gitignore",
+      "rule": "gitignore.mdc"
+    },
+    {
+      "pattern": "**/docker/template/src/**/*",
+      "rule": "source-code.mdc"
+    },
+    {
+      "pattern": "**/.woodpecker.yml",
+      "rule": "ci-pipeline.mdc"
+    }
+  ]
+} 

.cursor/rules/ci-pipeline.mdc

@@ -0,0 +1,5 @@
+---
+description:
+globs:
+alwaysApply: false
+---

.cursor/rules/docker-compose-files.mdc

@@ -0,0 +1,5 @@
+---
+description:
+globs:
+alwaysApply: false
+---

.cursor/rules/docker-files.mdc

@@ -0,0 +1,38 @@
+---
+description: 
+globs: Dockerfile,Dockerfile.*
+alwaysApply: false
+---
+# Docker Files
+
+## Dockerfiles
+- [docker/template/Dockerfile](mdc:docker/template/Dockerfile): Development/Base Dockerfile
+  - Used for local development and testing
+  - Referenced in [docker-compose.dev.yml](mdc:docker-compose.dev.yml)
+  
+- [docker/template/Dockerfile.production](mdc:docker/template/Dockerfile.production): Production-optimized Dockerfile
+  - Used for production deployments
+  - Referenced in [docker-compose.production.yml](mdc:docker-compose.production.yml)
+
+## Docker Compose Files
+- [docker-compose.dev.yml](mdc:docker-compose.dev.yml): Development setup
+  - Uses volume mounts for live code changes
+  - Configures development environment variables
+  - Mounts the [temp](mdc:temp) directory for local testing
+
+- [docker-compose.staging.yml](mdc:docker-compose.staging.yml): Staging build configuration
+  - Builds and tags the staging image
+  - Used by CI/CD for staging deployments
+
+- [docker-compose.production.yml](mdc:docker-compose.production.yml): Production build configuration
+  - Builds and tags the production image
+  - Used by CI/CD for production deployments
+
+## Stack Files
+- [stack.staging.yml](mdc:stack.staging.yml): Staging stack deployment
+  - Configures service deployment for staging environment
+  - Sets up Traefik routing rules
+
+- [stack.production.yml](mdc:stack.production.yml): Production stack deployment
+  - Configures service deployment for production environment
+  - Sets up Traefik routing rules with appropriate security headers

.cursor/rules/dockerfiles.mdc

@@ -0,0 +1,30 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Dockerfiles
+
+This project uses a multi-stage Dockerfile approach for different environments.
+
+## Development Dockerfile
+[docker/template/Dockerfile](mdc:docker/template/Dockerfile): Used for local development
+- Optimized for fast rebuilds and development workflow
+- Includes development tools and debugging capabilities
+- Used by [docker-compose.dev.yml](mdc:docker-compose.dev.yml)
+- Allows for volume mounting of source code
+
+## Production Dockerfile
+[docker/template/Dockerfile.production](mdc:docker/template/Dockerfile.production): Used for production deployments
+- Optimized for security, size, and performance
+- Removes development dependencies and tools
+- Used by [docker-compose.production.yml](mdc:docker-compose.production.yml)
+- Bakes the source code into the image
+
+## Guidelines
+- Keep base images consistent between environments
+- Use multi-stage builds to optimize image size
+- Pin specific versions of base images
+- Include proper healthchecks
+- Document any environment variables required
+- Optimize caching by ordering instructions appropriately (dependencies first, code last)

.cursor/rules/gitignore.mdc

@@ -0,0 +1,5 @@
+---
+description:
+globs:
+alwaysApply: false
+---

.cursor/rules/project-structure.mdc

@@ -0,0 +1,5 @@
+---
+description:
+globs:
+alwaysApply: false
+---

.cursor/rules/scripts.mdc

@@ -0,0 +1,5 @@
+---
+description:
+globs:
+alwaysApply: false
+---

.cursor/rules/source-code.mdc

@@ -0,0 +1,5 @@
+---
+description:
+globs:
+alwaysApply: false
+---

.cursor/rules/stack-files.mdc

@@ -0,0 +1,5 @@
+---
+description:
+globs:
+alwaysApply: false
+---

.cursor/rules/temp-directory.mdc

@@ -0,0 +1,5 @@
+---
+description:
+globs:
+alwaysApply: false
+---

README.md

@@ -0,0 +1,126 @@
+# Template Project
+
+This is a template project that follows a standardized structure for Docker-based applications.
+
+## Project Structure
+
+```
+./
+├── .woodpecker.yml          # CI configuration
+├── build-test-run.sh        # Convenience script for local development
+├── docker/
+│   └── template/           # Main application container
+│       ├── Dockerfile      # Base Dockerfile
+│       ├── Dockerfile.production  # Production-specific Dockerfile
+│       └── src/            # Application source code
+├── tests/                  # Test scripts
+├── temp/                   # Local testing scratch space
+├── docker-compose.dev.yml  # Docker Compose for local development
+├── docker-compose.production.yml
+├── docker-compose.staging.yml
+├── docker-compose.test.yml
+├── stack.staging.yml
+└── stack.production.yml
+```
+
+## Local Development
+
+### Quick Start
+
+The easiest way to get started with local development is to use the `build-test-run.sh` script:
+
+```bash
+./build-test-run.sh
+```
+
+This script will:
+1. Build the Docker images using docker-compose.dev.yml
+2. Run tests if available
+3. Start all services in the background
+4. Display the URL to access the application
+
+### Development Compose File
+
+The `docker-compose.dev.yml` file is designed for local development. It includes:
+- Volume mounts for code changes without rebuilding
+- Debug environment variables
+- Health checks
+- Local ports for easy access
+
+To use it directly:
+```bash
+# Build and start in one command
+docker compose -f docker-compose.dev.yml up --build
+
+# Run in the background
+docker compose -f docker-compose.dev.yml up -d
+
+# View logs
+docker compose -f docker-compose.dev.yml logs -f
+
+# Stop services
+docker compose -f docker-compose.dev.yml down
+```
+
+### Using the `temp` Directory
+
+The `./temp/` directory serves as a scratch space for local testing and development. It's designed to store temporary files that shouldn't be committed to version control, such as:
+
+- Test output logs (e.g., `test_output.log`)
+- Temporary build artifacts
+- Local configuration overrides
+- Mock data for testing
+- Debug logs and crash reports
+
+#### Example Usage
+
+1. Running tests with output:
+```bash
+# Test output will be written to ./temp/test_output.log
+./tests/run_tests.sh > ./temp/test_output.log
+```
+
+2. Local configuration:
+```bash
+# Create a local config override
+cp config.yml ./temp/local_config.yml
+# Edit local_config.yml for testing
+```
+
+3. Debug logs:
+```bash
+# Application debug logs
+docker-compose -f docker-compose.test.yml up > ./temp/debug.log
+```
+
+### Important Notes
+
+- The `./temp/` directory is git-ignored
+- Files in this directory are temporary and can be safely deleted
+- Use this directory for any files that shouldn't be committed to version control
+- The directory is mounted in test containers for easy access to test outputs
+
+## Development Workflow
+
+1. Start local development:
+```bash
+./build-test-run.sh
+# or
+docker compose -f docker-compose.dev.yml up --build
+```
+
+2. Run tests:
+```bash
+./tests/run_tests.sh
+```
+
+3. Check test outputs in `./temp/` directory
+
+4. Clean up temporary files:
+```bash
+rm -rf ./temp/*
+```
+
+## CI/CD
+
+The project uses Woodpecker CI for continuous integration. The `temp` directory is not included in CI builds to ensure clean, reproducible builds. 

build-test-run.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+set -e
+
+# Colors for terminal output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+echo -e "${YELLOW}Starting build-test-run script for local development${NC}"
+
+# Create temp directory if it doesn't exist
+mkdir -p ./temp
+
+# Log file for build output
+LOG_FILE="./temp/build-test-run.log"
+echo "Build started at $(date)" > $LOG_FILE
+
+# Step 1: Build the Docker images
+echo -e "${GREEN}Step 1: Building Docker images${NC}"
+echo "Building Docker images..." >> $LOG_FILE
+docker compose -f docker-compose.dev.yml build >> $LOG_FILE 2>&1
+if [ $? -ne 0 ]; then
+    echo -e "${RED}Build failed. Check $LOG_FILE for details.${NC}"
+    exit 1
+fi
+echo -e "${GREEN}Build completed successfully${NC}"
+
+# Step 2: Run tests if they exist
+if [ -f "./tests/run_tests.sh" ]; then
+    echo -e "${GREEN}Step 2: Running tests${NC}"
+    echo "Running tests..." >> $LOG_FILE
+    chmod +x ./tests/run_tests.sh
+    ./tests/run_tests.sh >> $LOG_FILE 2>&1
+    if [ $? -ne 0 ]; then
+        echo -e "${RED}Tests failed. Check $LOG_FILE for details.${NC}"
+        exit 1
+    fi
+    echo -e "${GREEN}Tests completed successfully${NC}"
+else
+    echo -e "${YELLOW}No test script found. Skipping tests.${NC}"
+fi
+
+# Step 3: Start the services
+echo -e "${GREEN}Step 3: Starting services${NC}"
+echo "Starting services..." >> $LOG_FILE
+docker compose -f docker-compose.dev.yml up -d >> $LOG_FILE 2>&1
+if [ $? -ne 0 ]; then
+    echo -e "${RED}Failed to start services. Check $LOG_FILE for details.${NC}"
+    exit 1
+fi
+
+# Get the URL for the service
+PORT=$(docker compose -f docker-compose.dev.yml port template 3000 2>/dev/null | cut -d: -f2)
+if [ -n "$PORT" ]; then
+    echo -e "${GREEN}Service is running at: ${YELLOW}http://localhost:$PORT${NC}"
+else
+    echo -e "${YELLOW}Service is running but couldn't determine the port.${NC}"
+fi
+
+echo -e "${GREEN}All services are up and running!${NC}"
+echo -e "To view logs: ${YELLOW}docker compose -f docker-compose.dev.yml logs -f${NC}"
+echo -e "To stop: ${YELLOW}docker compose -f docker-compose.dev.yml down${NC}"
+echo "Build and run completed at $(date)" >> $LOG_FILE 

docker-compose.dev.yml

@@ -0,0 +1,42 @@
+# Development configuration for local testing
+services:
+  template:
+    build:
+      context: ./docker/template
+      dockerfile: Dockerfile
+    image: template:dev
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./docker/template/src:/app/src
+      - ./temp:/app/temp
+    environment:
+      - NODE_ENV=development
+      - DEBUG=true
+      - LOG_LEVEL=debug
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+    networks:
+      - dev_network
+
+  # Add any additional services you need here
+  # Example:
+  # db:
+  #   image: postgres:14
+  #   environment:
+  #     - POSTGRES_PASSWORD=postgres
+  #     - POSTGRES_USER=postgres
+  #     - POSTGRES_DB=template
+  #   volumes:
+  #     - ./temp/postgres-data:/var/lib/postgresql/data
+  #   networks:
+  #     - dev_network
+
+networks:
+  dev_network:
+    driver: bridge