fix(postiz): generate .env file to prevent dotenv-cli crash (#40)

the postiz backend image uses dotenv-cli to load /app/.env, which
doesn't exist when config is only passed via docker environment vars.
generate postiz.env from root .env and mount it read-only. also handle
edge case where docker creates the file as a directory on bind mount
failure, and quote values to prevent dotenv-cli misparses.

.gitignore

@@ -11,6 +11,7 @@ dify/
 volumes/
 docker-compose.override.yml
 docker-compose.n8n-workers.yml
+postiz.env
 welcome/data.json
 welcome/changelog.json
 

AGENTS.md

@@ -1,31 +0,0 @@
-# Repository Guidelines
-
-## Project Structure & Module Organization
-- Core runtime config lives at the repo root: `docker-compose.yml`, `docker-compose.n8n-workers.yml`, and `Caddyfile`.
-- Installer and maintenance logic is in `scripts/` (install, update, doctor, cleanup, and helpers).
-- Service-specific assets are grouped by folder (examples: `n8n/`, `grafana/`, `prometheus/`, `searxng/`, `ragflow/`, `python-runner/`, `welcome/`).
-- Shared files for workflows are stored in `shared/` and mounted inside containers as `/data/shared`.
-
-## Build, Test, and Development Commands
-- `make install`: run the full installation wizard.
-- `make update` or `make git-pull`: refresh images and configuration (fork-friendly via `make git-pull`).
-- `make logs s=<service>`: tail a specific service’s logs (example: `make logs s=n8n`).
-- `make doctor`: run system checks for DNS/SSL/containers.
-- `make restart`, `make stop`, `make start`, `make status`: manage the compose stack.
-- `make clean` or `make clean-all`: remove unused Docker resources (`clean-all` is destructive).
-
-## Coding Style & Naming Conventions
-- Bash scripts in `scripts/` use `#!/bin/bash`, 4-space indentation, and uppercase constants. Match existing formatting.
-- Environment variable patterns are consistent: hostnames use `_HOSTNAME`, secrets use `_PASSWORD` or `_KEY`, and bcrypt hashes use `_PASSWORD_HASH`.
-- Services should not publish ports directly; external access goes through Caddy.
-
-## Testing Guidelines
-- There is no unit-test suite. Use syntax checks instead:
-- `docker compose -p localai config --quiet`
-- `bash -n scripts/install.sh` (and other edited scripts)
-- For installer changes, validate on a clean Ubuntu 24.04 LTS host and confirm profile selections start correctly.
-
-## Commit & Pull Request Guidelines
-- Commit messages follow Conventional Commits: `type(scope): summary` (examples in history include `fix(caddy): ...`, `docs(readme): ...`, `feat(postiz): ...`).
-- PRs should include a short summary, affected services/profiles, and test commands run.
-- Update `README.md` and `CHANGELOG.md` for user-facing changes or new services.

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [1.3.3] - 2026-02-27
+
+### Fixed
+- **Postiz** - Generate `postiz.env` file to prevent `dotenv-cli` crash in backend container (#40). Handles edge case where Docker creates the file as a directory, and quotes values to prevent misparses.
+
+## [1.3.2] - 2026-02-27
+
+### Fixed
+- **Docker Compose** - Respect `docker-compose.override.yml` for user customizations (#44). All compose file assembly points now include the override file when present.
+
+## [1.3.1] - 2026-02-27
+
+### Fixed
+- **Installer** - Skip n8n workflow import and worker configuration prompts when n8n profile is not selected
+
 ## [1.3.0] - 2026-02-27
 
 ### Added

CLAUDE.md

@@ -41,7 +41,8 @@ This is **n8n-install**, a Docker Compose-based installer that provides a compre
 - `scripts/download_top_workflows.sh`: Downloads community n8n workflows
 - `scripts/import_workflows.sh`: Imports workflows from `n8n/backup/workflows/` into n8n (used by `make import`)
 - `scripts/restart.sh`: Restarts services with proper compose file handling (used by `make restart`)
-- `scripts/setup_custom_tls.sh`: Configures custom TLS certificates (used by `make setup-tls`)
+- `scripts/setup_custom_tls.sh`: Configures custom TLS certificates (used by `make setup-tls`); supports `--remove` to revert to Let's Encrypt
+- `start_services.py`: Python orchestrator for service startup order, builds Docker images, handles external services (Supabase/Dify cloning, env preparation, startup), generates SearXNG secret key, stops existing containers. Uses `python-dotenv` (`dotenv_values`).
 
 **Project Name**: All docker-compose commands use `-p localai` (defined in Makefile as `PROJECT_NAME := localai`).
 
@@ -60,9 +61,9 @@ This is **n8n-install**, a Docker Compose-based installer that provides a compre
 7. `07_final_report.sh` - Display credentials and URLs
 8. `08_fix_permissions.sh` - Fix file ownership for non-root access
 
-The update flow (`scripts/update.sh`) similarly orchestrates: git fetch + reset → service selection → `apply_update.sh` → restart.
+The update flow (`scripts/update.sh`) similarly orchestrates: git fetch + reset → service selection → `apply_update.sh` → restart. During updates, `03_generate_secrets.sh --update` adds new variables from `.env.example` without regenerating existing ones (preserves user-set values).
 
-**Git update modes**: Default is `reset` (hard reset to origin). Set `GIT_MODE=merge` in `.env` for fork workflows (merges from upstream instead of hard reset). The `make git-pull` command uses merge mode.
+**Git update modes**: Default is `reset` (hard reset to origin). Set `GIT_MODE=merge` in `.env` for fork workflows (merges from upstream instead of hard reset). The `make git-pull` command uses merge mode. Git branch support is explicit: `GIT_SUPPORTED_BRANCHES=("main" "develop")` in `git.sh`; unknown branches warn and fall back to `main`.
 
 ## Common Development Commands
 
@@ -104,7 +105,7 @@ Follow this workflow when adding a new optional service (refer to `.claude/comma
 3. **.env.example**: Add `MYSERVICE_HOSTNAME=myservice.yourdomain.com` and credentials if using basic auth.
 4. **scripts/03_generate_secrets.sh**: Generate passwords and bcrypt hashes. Add to `VARS_TO_GENERATE` map.
 5. **scripts/04_wizard.sh**: Add service to `base_services_data` array for wizard selection.
-6. **scripts/databases.sh**: If service uses PostgreSQL, add database name to `INIT_DB_DATABASES` array.
+6. **scripts/databases.sh**: If service uses PostgreSQL, add database name to `INIT_DB_DATABASES` array. Database creation is idempotent (checks existence before creating). Note: Postiz also requires `temporal` and `temporal_visibility` databases.
 7. **scripts/generate_welcome_page.sh**: Add service to `SERVICES_ARRAY` for welcome dashboard.
 8. **welcome/app.js**: Add `SERVICE_METADATA` entry with name, description, icon, color, category.
 9. **scripts/07_final_report.sh**: Add service URL and credentials output using `is_profile_active "myservice"`.
@@ -165,9 +166,8 @@ This project uses [Semantic Versioning](https://semver.org/). When updating `CHA
 - **Template profile pattern**: `docker-compose.yml` defines `n8n-worker-template` and `n8n-runner-template` with `profiles: ["n8n-template"]` (never activated directly). `generate_n8n_workers.sh` uses these as templates to generate `docker-compose.n8n-workers.yml` with the actual worker/runner services.
 - **Scaling**: Change `N8N_WORKER_COUNT` in `.env` and run `bash scripts/generate_n8n_workers.sh`
 - **Code node libraries**: Configured via `n8n/n8n-task-runners.json` and `n8n/Dockerfile.runner`:
-  - JS packages installed via `pnpm add` in Dockerfile.runner
+  - **JavaScript runner**: packages installed via `pnpm add` in Dockerfile.runner; allowlist in `n8n-task-runners.json` (`NODE_FUNCTION_ALLOW_EXTERNAL`, `NODE_FUNCTION_ALLOW_BUILTIN`); default packages: `cheerio`, `axios`, `moment`, `lodash`
-  - Allowlist configured in `n8n-task-runners.json` (`NODE_FUNCTION_ALLOW_EXTERNAL`, `NODE_FUNCTION_ALLOW_BUILTIN`)
+  - **Python runner**: also configured in `n8n-task-runners.json`; uses `/opt/runners/task-runner-python/.venv/bin/python` with `N8N_RUNNERS_STDLIB_ALLOW: "*"` and `N8N_RUNNERS_EXTERNAL_ALLOW: "*"`
-  - Default packages: `cheerio`, `axios`, `moment`, `lodash`
 - Workflows can access the host filesystem via `/data/shared` (mapped to `./shared`)
 - `N8N_BLOCK_ENV_ACCESS_IN_NODE=false` allows Code nodes to access environment variables
 
@@ -177,7 +177,8 @@ This project uses [Semantic Versioning](https://semver.org/). When updating `CHA
 - Hostnames are passed via environment variables (e.g., `N8N_HOSTNAME`, `FLOWISE_HOSTNAME`)
 - Basic auth uses bcrypt hashes generated by `scripts/03_generate_secrets.sh` via Caddy's hash command
 - Never add `ports:` to services in docker-compose.yml; let Caddy handle all external access
-- **Caddy Addons** (`caddy-addon/`): Extend Caddy config without modifying the main Caddyfile. Files matching `site-*.conf` are auto-imported. TLS is controlled via `tls-snippet.conf` (all service blocks use `import service_tls`). See `caddy-addon/README.md` for details.
+- **Caddy Addons** (`caddy-addon/`): Extend Caddy config without modifying the main Caddyfile. Files matching `site-*.conf` are auto-imported (gitignored, user-created). TLS is controlled via `tls-snippet.conf` (all service blocks use `import service_tls`). See `caddy-addon/README.md` for details.
+- Custom TLS certificates go in `certs/` directory (gitignored), referenced as `/etc/caddy/certs/` inside the container
 
 ### External Compose Files (Supabase/Dify)
 
@@ -187,6 +188,7 @@ Complex services like Supabase and Dify maintain their own upstream docker-compo
 - `scripts/utils.sh` provides `get_*_compose()` getter functions and `build_compose_files_array()` includes them
 - `stop_all_services()` in `start_services.py` checks compose file existence (not profile) to ensure cleanup when a profile is removed
 - All external compose files use the same project name (`-p localai`) so containers appear together
+- **`docker-compose.override.yml`**: User customizations file (gitignored). Both `start_services.py` and `build_compose_files_array()` in `utils.sh` auto-detect and include it last (highest precedence). Users can override any service property without modifying tracked files.
 
 ### Secret Generation
 
@@ -195,6 +197,7 @@ The `scripts/03_generate_secrets.sh` script:
 - Creates bcrypt password hashes using Caddy's `hash-password` command
 - Preserves existing user-provided values in `.env`
 - Supports different secret types via `VARS_TO_GENERATE` map: `password:32`, `jwt`, `api_key`, `base64:64`, `hex:32`
+- When called with `--update` flag (during updates), only adds new variables without regenerating existing ones
 
 ### Utility Functions (scripts/utils.sh)
 
@@ -229,11 +232,24 @@ Common profiles:
 - `langfuse`: Langfuse observability (includes ClickHouse, MinIO, worker, web)
 - `cpu`, `gpu-nvidia`, `gpu-amd`: Ollama hardware profiles (mutually exclusive)
 - `cloudflare-tunnel`: Cloudflare Tunnel for zero-trust access (see `cloudflare-instructions.md`)
+- `supabase`: Supabase BaaS (external compose, cloned at runtime; mutually exclusive with `dify`)
+- `dify`: Dify AI platform (external compose, cloned at runtime; mutually exclusive with `supabase`)
 - `gost`: HTTP/HTTPS proxy for routing AI service outbound traffic
 - `python-runner`: Internal Python execution environment (no external access)
+- `searxng`, `letta`, `lightrag`, `libretranslate`, `crawl4ai`, `docling`, `waha`, `comfyui`, `paddleocr`, `ragapp`, `gotenberg`, `postiz`: Additional optional services
 
 ## Architecture Patterns
 
+### Docker Compose YAML Anchors
+
+`docker-compose.yml` defines reusable anchors at the top:
+- `x-logging: &default-logging` - `json-file` with `max-size: 1m`, `max-file: 1`
+- `x-proxy-env: &proxy-env` - HTTP/HTTPS proxy vars from `GOST_PROXY_URL`/`GOST_NO_PROXY`
+- `x-n8n: &service-n8n` - Full n8n service definition (reused by workers via `extends`)
+- `x-ollama: &service-ollama` - Ollama service definition (reused by CPU/GPU variants)
+- `x-init-ollama: &init-ollama` - Ollama model pre-puller (auto-pulls `qwen2.5:7b-instruct-q4_K_M` and `nomic-embed-text`)
+- `x-n8n-worker-runner: &service-n8n-worker-runner` - Runner template for worker generation
+
 ### Healthchecks
 
 Services should define healthchecks for proper dependency management:
@@ -310,6 +326,10 @@ Directories in `PRESERVE_DIRS` (defined in `scripts/utils.sh`) survive git updat
 
 These are backed up before `git reset --hard` and restored after.
 
+### Restart Behavior
+
+`scripts/restart.sh` stops all services first, then starts external stacks (Supabase/Dify) separately before the main stack (10s delay between). This is required because external compose files use relative volume paths that resolve from their own directory.
+
 ## Common Issues and Solutions
 
 ### Service won't start after adding
@@ -330,7 +350,11 @@ These are backed up before `git reset --hard` and restored after.
 ## File Locations
 
 - Shared files accessible by n8n: `./shared` (mounted as `/data/shared` in n8n)
+- n8n backup/workflows: `n8n/backup/workflows/` (mounted as `/backup` in n8n containers)
 - n8n storage: Docker volume `localai_n8n_storage`
+- Flowise storage: `~/.flowise` on host (mounted from user's home directory, not a named volume)
+- Custom TLS certificates: `certs/` (gitignored, mounted as `/etc/caddy/certs/`)
+- Caddy addon configs: `caddy-addon/site-*.conf` (gitignored, auto-imported)
 - Service-specific volumes: Defined in `volumes:` section at top of `docker-compose.yml`
 - Installation logs: stdout during script execution
 - Service logs: `docker compose -p localai logs <service>`
@@ -357,6 +381,10 @@ bash -n scripts/generate_n8n_workers.sh
 bash -n scripts/apply_update.sh
 bash -n scripts/update.sh
 bash -n scripts/install.sh
+bash -n scripts/restart.sh
+bash -n scripts/doctor.sh
+bash -n scripts/setup_custom_tls.sh
+bash -n scripts/docker_cleanup.sh
 ```
 
 ### Full Testing

VERSION

@@ -1 +1 @@
-1.3.0
+1.3.3

docker-compose.yml

@@ -906,6 +906,7 @@ services:
     volumes:
       - postiz-config:/config/
       - postiz-uploads:/uploads/
+      - ./postiz.env:/app/.env:ro
     depends_on:
       postgres:
         condition: service_healthy

scripts/05_configure_services.sh

@@ -27,6 +27,10 @@ init_paths
 # Ensure .env exists
 ensure_file_exists "$ENV_FILE"
 
+# Load COMPOSE_PROFILES early so is_profile_active works for all sections
+COMPOSE_PROFILES_VALUE="$(read_env_var COMPOSE_PROFILES)"
+COMPOSE_PROFILES="$COMPOSE_PROFILES_VALUE"
+
 # ----------------------------------------------------------------
 # Prompt for OpenAI API key (optional) using .env value as source of truth
 # ----------------------------------------------------------------
@@ -48,87 +52,89 @@ fi
 # ----------------------------------------------------------------
 # Logic for n8n workflow import (RUN_N8N_IMPORT)
 # ----------------------------------------------------------------
-log_subheader "n8n Workflow Import"
+if is_profile_active "n8n"; then
-final_run_n8n_import_decision="false"
+    log_subheader "n8n Workflow Import"
-require_whiptail
-if wt_yesno "Import n8n Workflows" "Import ~300 ready-made n8n workflows now? This can take ~30 minutes." "no"; then
-    final_run_n8n_import_decision="true"
-else
     final_run_n8n_import_decision="false"
-fi
+    require_whiptail
+    if wt_yesno "Import n8n Workflows" "Import ~300 ready-made n8n workflows now? This can take ~30 minutes." "no"; then
+        final_run_n8n_import_decision="true"
+    else
+        final_run_n8n_import_decision="false"
+    fi
 
-# Persist RUN_N8N_IMPORT to .env
+    # Persist RUN_N8N_IMPORT to .env
-write_env_var "RUN_N8N_IMPORT" "$final_run_n8n_import_decision"
+    write_env_var "RUN_N8N_IMPORT" "$final_run_n8n_import_decision"
+else
+    write_env_var "RUN_N8N_IMPORT" "false"
+fi
 
 
 # ----------------------------------------------------------------
 # Prompt for number of n8n workers
 # ----------------------------------------------------------------
-log_subheader "n8n Worker Configuration"
+if is_profile_active "n8n"; then
-EXISTING_N8N_WORKER_COUNT="$(read_env_var N8N_WORKER_COUNT)"
+    log_subheader "n8n Worker Configuration"
-require_whiptail
+    EXISTING_N8N_WORKER_COUNT="$(read_env_var N8N_WORKER_COUNT)"
-if [[ -n "$EXISTING_N8N_WORKER_COUNT" ]]; then
+    require_whiptail
-    N8N_WORKER_COUNT_CURRENT="$EXISTING_N8N_WORKER_COUNT"
+    if [[ -n "$EXISTING_N8N_WORKER_COUNT" ]]; then
-    N8N_WORKER_COUNT_INPUT_RAW=$(wt_input "n8n Workers (instances)" "Enter new number of n8n workers, or leave as current ($N8N_WORKER_COUNT_CURRENT)." "") || true
+        N8N_WORKER_COUNT_CURRENT="$EXISTING_N8N_WORKER_COUNT"
-    if [[ -z "$N8N_WORKER_COUNT_INPUT_RAW" ]]; then
+        N8N_WORKER_COUNT_INPUT_RAW=$(wt_input "n8n Workers (instances)" "Enter new number of n8n workers, or leave as current ($N8N_WORKER_COUNT_CURRENT)." "") || true
-        N8N_WORKER_COUNT="$N8N_WORKER_COUNT_CURRENT"
+        if [[ -z "$N8N_WORKER_COUNT_INPUT_RAW" ]]; then
-    else
+            N8N_WORKER_COUNT="$N8N_WORKER_COUNT_CURRENT"
-        if [[ "$N8N_WORKER_COUNT_INPUT_RAW" =~ ^0*[1-9][0-9]*$ ]]; then
+        else
-            N8N_WORKER_COUNT_TEMP="$((10#$N8N_WORKER_COUNT_INPUT_RAW))"
+            if [[ "$N8N_WORKER_COUNT_INPUT_RAW" =~ ^0*[1-9][0-9]*$ ]]; then
-            if [[ "$N8N_WORKER_COUNT_TEMP" -ge 1 ]]; then
+                N8N_WORKER_COUNT_TEMP="$((10#$N8N_WORKER_COUNT_INPUT_RAW))"
-                if wt_yesno "Confirm Workers" "Update n8n workers to $N8N_WORKER_COUNT_TEMP?" "yes"; then
+                if [[ "$N8N_WORKER_COUNT_TEMP" -ge 1 ]]; then
-                    N8N_WORKER_COUNT="$N8N_WORKER_COUNT_TEMP"
+                    if wt_yesno "Confirm Workers" "Update n8n workers to $N8N_WORKER_COUNT_TEMP?" "yes"; then
+                        N8N_WORKER_COUNT="$N8N_WORKER_COUNT_TEMP"
+                    else
+                        N8N_WORKER_COUNT="$N8N_WORKER_COUNT_CURRENT"
+                        log_info "Change declined. Keeping N8N_WORKER_COUNT at $N8N_WORKER_COUNT."
+                    fi
                 else
+                    log_warning "Invalid input '$N8N_WORKER_COUNT_INPUT_RAW'. Number must be positive. Keeping $N8N_WORKER_COUNT_CURRENT."
                     N8N_WORKER_COUNT="$N8N_WORKER_COUNT_CURRENT"
-                    log_info "Change declined. Keeping N8N_WORKER_COUNT at $N8N_WORKER_COUNT."
                 fi
             else
-                log_warning "Invalid input '$N8N_WORKER_COUNT_INPUT_RAW'. Number must be positive. Keeping $N8N_WORKER_COUNT_CURRENT."
+                log_warning "Invalid input '$N8N_WORKER_COUNT_INPUT_RAW'. Please enter a positive integer. Keeping $N8N_WORKER_COUNT_CURRENT."
                 N8N_WORKER_COUNT="$N8N_WORKER_COUNT_CURRENT"
             fi
-        else
-            log_warning "Invalid input '$N8N_WORKER_COUNT_INPUT_RAW'. Please enter a positive integer. Keeping $N8N_WORKER_COUNT_CURRENT."
-            N8N_WORKER_COUNT="$N8N_WORKER_COUNT_CURRENT"
         fi
-    fi
+    else
-else
+        while true; do
-    while true; do
+            N8N_WORKER_COUNT_INPUT_RAW=$(wt_input "n8n Workers" "Enter number of n8n workers to run (default 1)." "1") || true
-        N8N_WORKER_COUNT_INPUT_RAW=$(wt_input "n8n Workers" "Enter number of n8n workers to run (default 1)." "1") || true
+            N8N_WORKER_COUNT_CANDIDATE="${N8N_WORKER_COUNT_INPUT_RAW:-1}"
-        N8N_WORKER_COUNT_CANDIDATE="${N8N_WORKER_COUNT_INPUT_RAW:-1}"
+            if [[ "$N8N_WORKER_COUNT_CANDIDATE" =~ ^0*[1-9][0-9]*$ ]]; then
-        if [[ "$N8N_WORKER_COUNT_CANDIDATE" =~ ^0*[1-9][0-9]*$ ]]; then
+                N8N_WORKER_COUNT_VALIDATED="$((10#$N8N_WORKER_COUNT_CANDIDATE))"
-            N8N_WORKER_COUNT_VALIDATED="$((10#$N8N_WORKER_COUNT_CANDIDATE))"
+                if [[ "$N8N_WORKER_COUNT_VALIDATED" -ge 1 ]]; then
-            if [[ "$N8N_WORKER_COUNT_VALIDATED" -ge 1 ]]; then
+                    if wt_yesno "Confirm Workers" "Run $N8N_WORKER_COUNT_VALIDATED n8n worker(s)?" "yes"; then
-                if wt_yesno "Confirm Workers" "Run $N8N_WORKER_COUNT_VALIDATED n8n worker(s)?" "yes"; then
+                        N8N_WORKER_COUNT="$N8N_WORKER_COUNT_VALIDATED"
-                    N8N_WORKER_COUNT="$N8N_WORKER_COUNT_VALIDATED"
+                        break
-                    break
+                    fi
+                else
+                    log_error "Number of workers must be a positive integer."
                 fi
             else
-                log_error "Number of workers must be a positive integer."
+                log_error "Invalid input '$N8N_WORKER_COUNT_CANDIDATE'. Please enter a positive integer (e.g., 1, 2)."
             fi
-        else
+        done
-            log_error "Invalid input '$N8N_WORKER_COUNT_CANDIDATE'. Please enter a positive integer (e.g., 1, 2)."
+    fi
-        fi
+    # Ensure N8N_WORKER_COUNT is definitely set (should be by logic above)
-    done
+    N8N_WORKER_COUNT="${N8N_WORKER_COUNT:-1}"
+
+    # Persist N8N_WORKER_COUNT to .env
+    write_env_var "N8N_WORKER_COUNT" "$N8N_WORKER_COUNT"
+
+    # Generate worker-runner pairs configuration
+    # Each worker gets its own dedicated task runner sidecar
+    log_info "Generating n8n worker-runner pairs configuration..."
+    bash "$SCRIPT_DIR/generate_n8n_workers.sh"
 fi
-# Ensure N8N_WORKER_COUNT is definitely set (should be by logic above)
-N8N_WORKER_COUNT="${N8N_WORKER_COUNT:-1}"
-
-# Persist N8N_WORKER_COUNT to .env
-write_env_var "N8N_WORKER_COUNT" "$N8N_WORKER_COUNT"
-
-# Generate worker-runner pairs configuration
-# Each worker gets its own dedicated task runner sidecar
-log_info "Generating n8n worker-runner pairs configuration..."
-bash "$SCRIPT_DIR/generate_n8n_workers.sh"
 
 
 # ----------------------------------------------------------------
 # Cloudflare Tunnel Token (if cloudflare-tunnel profile is active)
 # ----------------------------------------------------------------
-COMPOSE_PROFILES_VALUE="$(read_env_var COMPOSE_PROFILES)"
-# Set COMPOSE_PROFILES for is_profile_active to work
-COMPOSE_PROFILES="$COMPOSE_PROFILES_VALUE"
-
 if is_profile_active "cloudflare-tunnel"; then
     log_subheader "Cloudflare Tunnel"
     existing_cf_token="$(read_env_var CLOUDFLARE_TUNNEL_TOKEN)"

scripts/restart.sh

@@ -10,6 +10,7 @@
 #   - docker-compose.n8n-workers.yml (if exists and n8n profile active)
 #   - supabase/docker/docker-compose.yml (if exists and supabase profile active)
 #   - dify/docker/docker-compose.yaml (if exists and dify profile active)
+#   - docker-compose.override.yml (if exists, user overrides with highest precedence)
 #
 # Usage: bash scripts/restart.sh
 # =============================================================================
@@ -33,6 +34,20 @@ EXTERNAL_SERVICE_INIT_DELAY=10
 # Build compose files array (sets global COMPOSE_FILES)
 build_compose_files_array
 
+# Ensure postiz.env exists if Postiz is enabled (required for volume mount)
+# This is a safety net for cases where restart runs without start_services.py
+# (e.g., git pull + make restart instead of make update)
+if is_profile_active "postiz"; then
+    if [ -d "$PROJECT_ROOT/postiz.env" ]; then
+        log_warning "postiz.env exists as a directory (created by Docker). Removing and recreating as file."
+        rm -rf "$PROJECT_ROOT/postiz.env"
+        touch "$PROJECT_ROOT/postiz.env"
+    elif [ ! -f "$PROJECT_ROOT/postiz.env" ]; then
+        log_warning "postiz.env not found, creating empty file. Run 'make update' to generate full config."
+        touch "$PROJECT_ROOT/postiz.env"
+    fi
+fi
+
 log_info "Restarting services..."
 log_info "Using compose files: ${COMPOSE_FILES[*]}"
 
@@ -71,6 +86,10 @@ MAIN_COMPOSE_FILES=("-f" "$PROJECT_ROOT/docker-compose.yml")
 if path=$(get_n8n_workers_compose); then
     MAIN_COMPOSE_FILES+=("-f" "$path")
 fi
+OVERRIDE_COMPOSE="$PROJECT_ROOT/docker-compose.override.yml"
+if [ -f "$OVERRIDE_COMPOSE" ]; then
+    MAIN_COMPOSE_FILES+=("-f" "$OVERRIDE_COMPOSE")
+fi
 
 # Start main services
 log_info "Starting main services..."

scripts/utils.sh

@@ -353,6 +353,7 @@ get_dify_compose() {
 }
 
 # Build array of all active compose files (main + external services)
+# Appends docker-compose.override.yml last if it exists (user overrides, highest precedence)
 # IMPORTANT: Requires COMPOSE_PROFILES to be set before calling (via load_env)
 # Usage: build_compose_files_array; docker compose "${COMPOSE_FILES[@]}" up -d
 # Result is stored in global COMPOSE_FILES array
@@ -369,6 +370,12 @@ build_compose_files_array() {
     if path=$(get_dify_compose); then
         COMPOSE_FILES+=("-f" "$path")
     fi
+
+    # Include user overrides last (highest precedence)
+    local override="$PROJECT_ROOT/docker-compose.override.yml"
+    if [ -f "$override" ]; then
+        COMPOSE_FILES+=("-f" "$override")
+    fi
 }
 
 #=============================================================================

start_services.py

@@ -166,6 +166,76 @@ def prepare_dify_env():
     with open(env_path, 'w') as f:
         f.write("\n".join(lines) + "\n")
 
+def is_postiz_enabled():
+    """Check if 'postiz' is in COMPOSE_PROFILES in .env file."""
+    env_values = dotenv_values(".env")
+    compose_profiles = env_values.get("COMPOSE_PROFILES", "")
+    return "postiz" in compose_profiles.split(',')
+
+def prepare_postiz_env():
+    """Generate postiz.env for mounting as /app/.env in Postiz container.
+
+    The Postiz image uses dotenv-cli (dotenv -e ../../.env) to load config.
+    Always regenerated to reflect current .env values.
+    """
+    if not is_postiz_enabled():
+        print("Postiz is not enabled, skipping env preparation.")
+        return
+
+    print("Generating postiz.env from root .env values...")
+    root_env = dotenv_values(".env")
+
+    hostname = root_env.get("POSTIZ_HOSTNAME", "")
+    frontend_url = f"https://{hostname}" if hostname else ""
+
+    env_vars = {
+        "BACKEND_INTERNAL_URL": "http://localhost:3000",
+        "DATABASE_URL": f"postgresql://postgres:{root_env.get('POSTGRES_PASSWORD', '')}@postgres:5432/{root_env.get('POSTIZ_DB_NAME', 'postiz')}?schema=postiz",
+        "DISABLE_REGISTRATION": root_env.get("POSTIZ_DISABLE_REGISTRATION", "false"),
+        "FRONTEND_URL": frontend_url,
+        "IS_GENERAL": "true",
+        "JWT_SECRET": root_env.get("JWT_SECRET", ""),
+        "MAIN_URL": frontend_url,
+        "NEXT_PUBLIC_BACKEND_URL": f"{frontend_url}/api" if frontend_url else "",
+        "NEXT_PUBLIC_UPLOAD_DIRECTORY": "/uploads",
+        "REDIS_URL": "redis://redis:6379",
+        "STORAGE_PROVIDER": "local",
+        "TEMPORAL_ADDRESS": "temporal:7233",
+        "UPLOAD_DIRECTORY": "/uploads",
+    }
+
+    # Social media API keys — direct pass-through from root .env
+    social_keys = [
+        "X_API_KEY", "X_API_SECRET",
+        "LINKEDIN_CLIENT_ID", "LINKEDIN_CLIENT_SECRET",
+        "REDDIT_CLIENT_ID", "REDDIT_CLIENT_SECRET",
+        "GITHUB_CLIENT_ID", "GITHUB_CLIENT_SECRET",
+        "BEEHIIVE_API_KEY", "BEEHIIVE_PUBLICATION_ID",
+        "THREADS_APP_ID", "THREADS_APP_SECRET",
+        "FACEBOOK_APP_ID", "FACEBOOK_APP_SECRET",
+        "YOUTUBE_CLIENT_ID", "YOUTUBE_CLIENT_SECRET",
+        "TIKTOK_CLIENT_ID", "TIKTOK_CLIENT_SECRET",
+        "PINTEREST_CLIENT_ID", "PINTEREST_CLIENT_SECRET",
+        "DRIBBBLE_CLIENT_ID", "DRIBBBLE_CLIENT_SECRET",
+        "DISCORD_CLIENT_ID", "DISCORD_CLIENT_SECRET",
+        "DISCORD_BOT_TOKEN_ID",
+        "SLACK_ID", "SLACK_SECRET", "SLACK_SIGNING_SECRET",
+        "MASTODON_URL", "MASTODON_CLIENT_ID", "MASTODON_CLIENT_SECRET",
+    ]
+    for key in social_keys:
+        env_vars[key] = root_env.get(key, "")
+
+    # Handle case where Docker created postiz.env as a directory
+    if os.path.isdir("postiz.env"):
+        print("Warning: postiz.env exists as a directory (likely created by Docker). Removing...")
+        shutil.rmtree("postiz.env")
+
+    with open("postiz.env", 'w') as f:
+        for key, value in env_vars.items():
+            f.write(f'{key}="{value}"\n')
+
+    print(f"Generated postiz.env with {len(env_vars)} variables.")
+
 def stop_existing_containers():
     """Stop and remove existing containers for our unified project ('localai')."""
     print("Stopping and removing existing containers for the unified project 'localai'...")
@@ -195,6 +265,11 @@ def stop_existing_containers():
     if os.path.exists(n8n_workers_compose_path):
         cmd.extend(["-f", n8n_workers_compose_path])
 
+    # Include user overrides if present
+    override_path = "docker-compose.override.yml"
+    if os.path.exists(override_path):
+        cmd.extend(["-f", override_path])
+
     cmd.extend(["down"])
     run_command(cmd)
 
@@ -230,6 +305,11 @@ def start_local_ai():
     if os.path.exists(n8n_workers_compose_path):
         compose_files.extend(["-f", n8n_workers_compose_path])
 
+    # Include user overrides if present (must be last for highest precedence)
+    override_path = "docker-compose.override.yml"
+    if os.path.exists(override_path):
+        compose_files.extend(["-f", override_path])
+
     # Explicitly build services and pull newer base images first.
     print("Checking for newer base images and building services...")
     build_cmd = ["docker", "compose", "-p", "localai"] + compose_files + ["build", "--pull"]
@@ -394,7 +474,10 @@ def main():
     # Generate SearXNG secret key and check docker-compose.yml
     generate_searxng_secret_key()
     check_and_fix_docker_compose_for_searxng()
-    
+
+    # Generate Postiz env file
+    prepare_postiz_env()
+
     stop_existing_containers()
     
     # Start Supabase first