Implementation:Langgenius Dify Init Permissions Container

Knowledge Sources	Dify
Domains	DevOps, Deployment, Storage, Security
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for setting filesystem ownership on Dify's storage volumes using a busybox init container with idempotency, provided by the init_permissions service in docker/docker-compose.yaml.

Description

The init_permissions service is defined at lines 699-715 of docker-compose.yaml. It uses a busybox:latest image to run a shell script that:

Checks for the existence of a flag file at /app/api/storage/.init_permissions.
If the flag exists, the container prints "Permissions already initialized" and exits immediately (idempotent skip).
If the flag does not exist, it runs chown -R 1001:1001 /app/api/storage to recursively set ownership.
After a successful chown, it creates the flag file with touch.

The API and worker services both declare a dependency on this init container:

depends_on:
  init_permissions:
    condition: service_completed_successfully

This ensures the permission fix completes before any application process attempts to read or write storage.

Usage

This service runs automatically as part of docker compose up. No manual invocation is needed. To force re-initialization of permissions (e.g., after manually changing volume ownership), delete the flag file:

rm docker/volumes/app/storage/.init_permissions
docker compose up -d

Code Reference

Source Location: docker/docker-compose.yaml, lines 699-715

Signature:

init_permissions:
  image: busybox:latest
  command:
    - sh
    - -c
    - |
      FLAG_FILE="/app/api/storage/.init_permissions"
      if [ -f "$${FLAG_FILE}" ]; then
        echo "Permissions already initialized. Exiting."
        exit 0
      fi
      echo "Initializing permissions for /app/api/storage"
      chown -R 1001:1001 /app/api/storage && touch "$${FLAG_FILE}"
      echo "Permissions initialized. Exiting."
  volumes:
    - ./volumes/app/storage:/app/api/storage
  restart: "no"

Import statement: Not applicable (Docker Compose service definition).

I/O Contract

Inputs

Parameter	Type	Required	Default	Description
Volume mount	Directory	Yes	./volumes/app/storage	Host directory mounted into the container at `/app/api/storage`
Target UID:GID	Integer pair	Yes (hardcoded)	1001:1001	The user and group ID that Dify application containers run as
Flag file path	String	Yes (hardcoded)	/app/api/storage/.init_permissions	Sentinel file indicating permissions have already been set

Outputs

Output	Type	Description
Correct ownership	Filesystem state	All files and directories under `/app/api/storage` are owned by 1001:1001
Flag file	File	`.init_permissions` created in the storage root, preventing redundant `chown` on future runs
Exit code 0	Process exit	Signals `service_completed_successfully` to Docker Compose, unblocking dependent services

Usage Examples

First-time deployment (permissions not yet initialized):

cd docker
docker compose up -d

# init_permissions container output:
# "Initializing permissions for /app/api/storage"
# "Permissions initialized. Exiting."
# -> api and worker containers start after init completes

Subsequent restart (permissions already initialized):

docker compose up -d

# init_permissions container output:
# "Permissions already initialized. Exiting."
# -> Exits immediately, api and worker start without delay

Force re-initialization after volume repair:

# Remove the flag file to force chown on next startup
rm ./volumes/app/storage/.init_permissions

docker compose up -d
# init_permissions runs chown again

Verify current ownership:

ls -la ./volumes/app/storage/
# Expected: drwxr-xr-x  ... 1001 1001 ... storage/

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment