@panoptic-it-solutions/coolify-setup 1.1.33 → 1.1.34

package/README.md

@@ -90,3 +90,4 @@ Files generated:
 ## License
 
 MIT
+

package/dist/index.js

@@ -206,6 +206,24 @@ async function main() {
     console.log('   • Add environment variables in Coolify');
     console.log('   • Generate domain (replace random string with app name)');
     console.log('   • Deploy\n');
+    // Show important tip about Docker networking if services are included
+    if (response.includePostgres || response.includeRedis || response.includeMinio) {
+        console.log(chalk.bgYellow.black.bold(' ⚠️  IMPORTANT: Docker Networking '));
+        console.log(chalk.yellow('\n   Use SERVICE NAMES, not localhost, in environment variables:\n'));
+        if (response.includePostgres) {
+            console.log(chalk.red('   ❌ DATABASE_URL=postgresql://user:pass@localhost:5432/db'));
+            console.log(chalk.green('   ✅ DATABASE_URL=postgresql://user:pass@postgres:5432/db\n'));
+        }
+        if (response.includeRedis) {
+            console.log(chalk.red('   ❌ REDIS_URL=redis://localhost:6379'));
+            console.log(chalk.green('   ✅ REDIS_URL=redis://redis:6379\n'));
+        }
+        if (response.includeMinio) {
+            console.log(chalk.red('   ❌ MINIO_ENDPOINT=http://localhost:9000'));
+            console.log(chalk.green('   ✅ MINIO_ENDPOINT=http://minio:9000\n'));
+        }
+        console.log(chalk.yellow('   Docker containers use service names for internal DNS resolution.\n'));
+    }
     console.log(chalk.bold('Branching Strategy:\n'));
     console.log('   develop     → Default branch, main development');
     console.log('   feature/**  → New features');

package/dist/templates/claude-rules.js

@@ -34,12 +34,31 @@ This project uses a trunk-based development workflow with deployment branches:
 
 3. **Staging Deployment**: Merge PR to \`staging\`
    - Coolify auto-deploys to staging server
-   - GitHub Actions creates PR to \`main\`
+   - GitHub Actions runs semantic versioning workflow
+   - Creates \`staging-v*\` tags based on conventional commits
    - Test changes in staging environment
 
-4. **Production Deployment**: Merge PR to \`main\`
+4. **Production Deployment**: Create PR from \`staging\` to \`main\`
+   - Review changes and merge
    - Coolify auto-deploys to production server
 
+### Conventional Commits
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) for automatic semantic versioning on the staging branch:
+
+| Commit Type | Version Bump | Example |
+|-------------|--------------|---------|
+| \`feat:\` | Minor (0.X.0) | \`feat: add user authentication\` |
+| \`feat!:\` or \`BREAKING CHANGE:\` | Major (X.0.0) | \`feat!: redesign API endpoints\` |
+| \`fix:\` | Patch (0.0.X) | \`fix: resolve login timeout\` |
+| Other | Patch (0.0.X) | \`chore: update dependencies\` |
+
+The staging version workflow automatically:
+- Detects version bump type from commit messages since last staging tag
+- Bumps version in package.json
+- Creates a \`staging-v*\` tag
+- Generates changelog with features, fixes, and other changes
+
 ### Branch Protection Rules
 
 - \`develop\` is the default branch
@@ -164,6 +183,94 @@ When adding services that need baked-in configs:
    - Sync the new Dockerfile to the deploy branch
    - Update image tags in docker-compose.yml via sed
 
+## Docker Compose Port Configuration
+
+### Use \`expose\` Instead of \`ports\`
+
+Coolify handles port mapping and domain routing automatically. Services should use \`expose\` to make ports available to Coolify without binding directly to host ports:
+
+\`\`\`yaml
+# CORRECT - Let Coolify handle port mapping
+app:
+  image: registry/app:latest
+  expose:
+    - "3000"
+
+minio:
+  image: minio/minio:latest
+  expose:
+    - "9000"
+    - "9001"
+\`\`\`
+
+\`\`\`yaml
+# AVOID - Direct port binding conflicts with Coolify
+app:
+  ports:
+    - "3000:3000"
+\`\`\`
+
+### Internal-Only Services
+
+Services like PostgreSQL and Redis should have no \`ports\` or \`expose\` directives. They communicate internally via Docker networking.
+
+## Docker Networking - Service Names vs localhost
+
+**CRITICAL**: In Docker Compose, containers communicate using **service names**, NOT \`localhost\`.
+
+| Variable | ❌ WRONG | ✅ CORRECT |
+|----------|----------|-----------|
+| \`DATABASE_URL\` | \`@localhost:5432\` | \`@postgres:5432\` |
+| \`REDIS_URL\` | \`redis://localhost:6379\` | \`redis://redis:6379\` |
+| \`MINIO_ENDPOINT\` | \`http://localhost:9000\` | \`http://minio:9000\` |
+
+### Why?
+
+- **\`localhost\`** inside a container refers to **that container itself** - useless for cross-container communication
+- **Service names** (e.g., \`postgres\`, \`redis\`, \`minio\`) are resolved by Docker's internal DNS to the correct container IP
+
+### Service Names from docker-compose.yml
+
+\`\`\`yaml
+services:
+  app:        # Other containers reach this as "app"
+  postgres:   # Other containers reach this as "postgres"
+  redis:      # Other containers reach this as "redis"
+  minio:      # Other containers reach this as "minio"
+\`\`\`
+
+### Common Mistakes in Coolify Environment Variables
+
+When setting environment variables in Coolify, ensure you use service names:
+
+\`\`\`bash
+# ❌ WRONG - will fail to connect
+DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
+
+# ✅ CORRECT - uses Docker service name
+DATABASE_URL=postgresql://user:pass@postgres:5432/mydb
+\`\`\`
+
+### Internal Services Configuration
+
+\`\`\`yaml
+# PostgreSQL - internal only (most secure)
+postgres:
+  image: postgres:16-alpine
+  volumes:
+    - postgres-data:/var/lib/postgresql/data
+  healthcheck:
+    test: ["CMD-SHELL", "pg_isready -U postgres"]
+  # No ports or expose - only accessible within Docker network
+
+# Redis - internal only
+redis:
+  image: redis:7-alpine
+  volumes:
+    - redis-data:/data
+  # No ports or expose - only accessible within Docker network
+\`\`\`
+
 ## Private Registry Configuration
 
 This project uses a private registry at \`10.0.0.2:5000\`. The staging server has \`insecure-registries\` configured, but Coolify's helper container may not inherit this. Pre-pulling images on the target server can help avoid registry issues.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panoptic-it-solutions/coolify-setup",
-  "version": "1.1.33",
+  "version": "1.1.34",
   "description": "CLI tool for setting up Coolify deployment on Panoptic projects",
   "type": "module",
   "main": "dist/index.js",