From d900d905de8b8acc088f0bc9a4c03d149b0e048e Mon Sep 17 00:00:00 2001
From: Oussama Douhou <oussama.douhou@gmail.com>
Date: Tue, 13 Jan 2026 15:52:17 +0100
Subject: [PATCH] docs: add critical Docker Compose custom command
 configuration

- Document requirement for custom compose command with -f flag
- Add troubleshooting section for 'no configuration file provided' error
- Include examples for dev/staging/prod environments
- Explain why Dokploy needs explicit -f flag for non-default filenames

Resolves issue where Dokploy couldn't find docker-compose.prod.yml
---
 docs/DOKPLOY_DEPLOYMENT.md | 76 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 74 insertions(+), 2 deletions(-)

diff --git a/docs/DOKPLOY_DEPLOYMENT.md b/docs/DOKPLOY_DEPLOYMENT.md
index 142d485..7a16e24 100644
--- a/docs/DOKPLOY_DEPLOYMENT.md
+++ b/docs/DOKPLOY_DEPLOYMENT.md
@@ -201,12 +201,48 @@ The portal's docker-compose files use Dokploy's variable syntax to reference the
    SHARED_ENVIRONMENT_ID=${{project.SHARED_ENVIRONMENT_ID}}
    ```
 
-4. **Configure Webhook**:
+4. **⚠️ CRITICAL: Configure Custom Docker Compose Command**:
+   
+   Because we use non-default compose file names (`docker-compose.dev.yml`, `docker-compose.prod.yml`, etc.), you **MUST** configure a custom command in Dokploy.
+   
+   **In Dokploy UI:**
+   - Go to the application **Settings** or **Advanced** tab
+   - Find **"Custom Command"** or **"Docker Compose Command"** field
+   - Set it to:
+     ```bash
+     compose -p <app-name> -f ./docker-compose.dev.yml up -d --remove-orphans --pull always
+     ```
+   
+   **Replace `<app-name>`** with your actual application name from Dokploy (e.g., `aistackportal-portal-0rohwx`)
+   
+   **Replace `docker-compose.dev.yml`** with the appropriate file for each environment:
+   - Dev: `docker-compose.dev.yml`
+   - Staging: `docker-compose.staging.yml`
+   - Production: `docker-compose.prod.yml`
+   
+   **Why this is required:**
+   - Dokploy's default command is `docker compose up -d` without the `-f` flag
+   - Without `-f`, docker looks for `docker-compose.yml` (which doesn't exist)
+   - This causes the error: `no configuration file provided: not found`
+   
+   **Full examples:**
+   ```bash
+   # Dev
+   compose -p aistackportal-deployer-dev-xyz123 -f ./docker-compose.dev.yml up -d --remove-orphans --pull always
+   
+   # Staging  
+   compose -p aistackportal-deployer-staging-abc456 -f ./docker-compose.staging.yml up -d --remove-orphans --pull always
+   
+   # Production
+   compose -p aistackportal-portal-0rohwx -f ./docker-compose.prod.yml up -d --remove-orphans --pull always
+   ```
+
+5. **Configure Webhook**:
    - Event: **Push**
    - Branch: `dev`
    - This will auto-deploy when you push to dev branch
 
-5. **Deploy**
+6. **Deploy**
 
 ### Step 2: Create Staging Application
 
@@ -414,6 +450,42 @@ Common issues:
    ```
 3. **Check environment variables**: Make sure all required vars are set
 
+### Error: "no configuration file provided: not found"
+
+**Symptom:**
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║ Command: docker compose up -d --force-recreate --pull always                 ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+no configuration file provided: not found
+Error: ❌ Docker command failed
+```
+
+**Cause:** Dokploy is looking for the default `docker-compose.yml` file, which doesn't exist. We use environment-specific files (`docker-compose.dev.yml`, `docker-compose.prod.yml`, etc.).
+
+**Solution:** Configure a **custom Docker Compose command** in Dokploy:
+
+1. Go to your application in Dokploy UI
+2. Navigate to **Settings** → **Advanced** (or similar section)
+3. Find **"Custom Command"** field
+4. Set it to:
+   ```bash
+   compose -p <app-name> -f ./docker-compose.{env}.yml up -d --remove-orphans --pull always
+   ```
+   
+   Replace:
+   - `<app-name>` with your actual Dokploy app name (e.g., `aistackportal-portal-0rohwx`)
+   - `{env}` with `dev`, `staging`, or `prod`
+   
+   **Example for production:**
+   ```bash
+   compose -p aistackportal-portal-0rohwx -f ./docker-compose.prod.yml up -d --remove-orphans --pull always
+   ```
+
+5. Save and redeploy
+
+**Why the `-f` flag is needed:** Docker Compose defaults to looking for `docker-compose.yml`. The `-f` flag explicitly specifies which file to use.
+
 ### Health Check Failing
 
 ```bash