Using local and s3 storage in docker compose setup #1026 (#1030)

* update compose file, Dockerfiles, disk.ts

* remove debugging console log

* remove default profile

* Update comments on disk.ts

* update AWS config error message (fix linter issue)

* add comments to Dockerfiles, update storage configuration docs

Author: Bald1nh0

.env.example

@@ -57,11 +57,13 @@ SENTRY_PROJECT=
 DRIVE_DISK=local # options: local, s3
 
 # Paths for local storage (optional)
-FILE_PUBLIC_PATH= # e.g files
-FILES_STORAGE_PATH= # e.g /app/storage/files
-PUBLIC_FILES_STORAGE_PATH= # e.g /app/storage/public/files (IMPORTANT: has to be in nextjs's public folder)
+FILE_STORAGE_ROOT_PATH="/app/storage/files" # e.g /app/storage/files
+FILE_PUBLIC_PATH="files" # e.g files
+FILES_STORAGE_PATH="/app/storage/files" # e.g /app/storage/files
+PUBLIC_FILES_STORAGE_PATH="/app/apps/web/public/files" # e.g /app/storage/public/files (IMPORTANT: has to be in nextjs's public folder)
 
 # AWS S3 (optional)
+# If you are using AWS IAM roles, you can skip AWS_ACCESS_KEY and AWS_ACCESS_SECRET
 ASW_REGION=
 AWS_ACCESS_KEY=
 AWS_ACCESS_SECRET=

apps/gateway/docker/Dockerfile

@@ -86,6 +86,12 @@ RUN apk add --no-cache \
 
 RUN addgroup --system --gid 1001 nodejs
 RUN adduser --system --uid 1001 latitude
+# Set permissions for local storage
+# User ID and Group ID 1001 is used to match the user 'latitude' and group 'nodejs' in the builder image.
+RUN set -e; \
+    mkdir -p /app/storage/files; \
+    mkdir -p /app/apps/web/public/files; \
+    chown -R 1001:1001 /app/storage/files /app/apps/web/public/files
 USER latitude
 
 WORKDIR /app

apps/web/docker/Dockerfile

@@ -156,6 +156,12 @@ COPY --from=builder --chown=nodejs:nextjs /app/apps/web/.next/static ./apps/web/
 # Copy all node_modules to ensure dependencies are available
 COPY --from=builder --chown=nodejs:nextjs /app/node_modules ./node_modules
 COPY --from=builder --chown=nodejs:nextjs /app/apps/web/node_modules ./apps/web/node_modules
+# Set permissions for local storage
+# User ID and Group ID 1001 is used to match the user 'nextjs' and group 'nodejs' in the runner image.
+RUN set -e; \
+    mkdir -p /app/storage/files; \
+    mkdir -p /app/apps/web/public/files; \
+    chown -R 1001:1001 /app/storage/files /app/apps/web/public/files
 
 USER nextjs
 

apps/workers/docker/Dockerfile

@@ -74,6 +74,12 @@ RUN apk add --no-cache \
 
 RUN addgroup --system --gid 1001 nodejs
 RUN adduser --system --uid 1001 latitude
+# Set permissions for local storage
+# User ID and Group ID 1001 is used to match the user 'latitude' and group 'nodejs' in the runner image.
+RUN set -e; \
+    mkdir -p /app/storage/files; \
+    mkdir -p /app/apps/web/public/files; \
+    chown -R 1001:1001 /app/storage/files /app/apps/web/public/files
 USER latitude
 
 WORKDIR /app

docker-compose.yml

@@ -1,6 +1,9 @@
 x-common-service: &common-service
   env_file:
     - .env
+  volumes:
+    - shared-storage:/app/storage/files:rw
+    - shared-storage:/app/apps/web/public/files:rw
   depends_on:
     - db
     - redis
@@ -175,7 +178,8 @@ services:
     build:
       context: .
       dockerfile: packages/core/docker/Dockerfile
-
+    labels:
+      - "traefik.enable=false"
     depends_on:
       - db
     profiles:
@@ -197,7 +201,6 @@ services:
     build:
       context: .
       dockerfile: apps/gateway/docker/Dockerfile
-
     profiles:
       - local
 
@@ -214,7 +217,6 @@ services:
     build:
       context: .
       dockerfile: apps/workers/docker/Dockerfile
-
     profiles:
       - local
 
@@ -231,7 +233,6 @@ services:
     build:
       context: .
       dockerfile: apps/websockets/docker/Dockerfile
-
     profiles:
       - local
 
@@ -245,4 +246,7 @@ services:
 # You need to create external network for Traefik to work (docker network create web)
 networks:
   web:
-    external: true
+    external: true
+
+volumes:
+  shared-storage:

docs/guides/self-hosted/production.mdx

@@ -71,7 +71,67 @@ Make sure this network is created before running the containers with  `docker co
 - **Storage Configuration**:
 
   - `DRIVE_DISK`: Choose between `local` or `s3` for file storage
-  - AWS S3 credentials (if using S3 storage)
+    1. `local` file storage configuration:
+      - Files are stored locally on the host machine using Docker volumes.
+      - Default variables used:
+
+        ```bash
+        # Paths for local storage (optional)
+        FILE_STORAGE_ROOT_PATH="/app/storage/files" # e.g /app/storage/files
+        FILE_PUBLIC_PATH="files" # e.g files
+        FILES_STORAGE_PATH="/app/storage/files" # e.g /app/storage/files
+        PUBLIC_FILES_STORAGE_PATH="/app/apps/web/public/files" # e.g /app/storage/public/files (IMPORTANT: has to be in nextjs's public folder)
+        ```
+
+    2. `s3` AWS S3 storage configuration:
+      - With environment variables (for convenience/legacy):
+        You explicitly provide AWS credentials (AWS_ACCESS_KEY and AWS_ACCESS_SECRET) via .env file.
+        Required variables:
+
+        ```bash
+        AWS_ACCESS_KEY=your-access-key-here
+        AWS_ACCESS_SECRET=your-secret-here
+        AWS_REGION=us-east-1
+        S3_BUCKET=app-files-bucket
+        PUBLIC_S3_BUCKET=public-files-bucket
+        ```
+      - AWS S3 with IAM Roles (recommended):
+        No explicit AWS keys needed!
+        Use IAM Roles attached to your AWS services (ECS, EC2, Lambda).
+        Ensure AWS resource has proper IAM Role with S3 access (GetObject, PutObject, DeleteObject).
+        Only required environment variables (no keys explicitly stored):
+
+        ```bash
+        AWS_REGION=us-east-1
+        S3_BUCKET=app-files-bucket
+        PUBLIC_S3_BUCKET=public-files-bucket
+        ```
+        How to configure IAM Role (example):
+        1. Go to AWS IAM → Create Role.
+        2. Select trusted entity type (e.g., AWS Service).
+        3. Attach policy that allows access to required S3 buckets.
+
+        ```json
+        {
+          "Version": "2012-10-17",
+          "Statement": [{
+            "Effect": "Allow",
+            "Action": [
+              "s3:GetObject",
+              "s3:PutObject",
+              "s3:DeleteObject",
+              "s3:ListBucket"
+            ],
+            "Resource": [
+              "arn:aws:s3:::your-bucket-name-here",
+              "arn:aws:s3:::your-bucket-name-here/*"
+            ]
+          }]
+        }
+        ```
+        4. Attach this IAM role to AWS infrastructure (EC2 Instance / ECS Task Definition / Lambda function).
+
+        AWS SDK automatically handles credentials from attached IAM roles.
 
 - **Optional Features**:
   - Sentry integration for error tracking

packages/core/src/lib/disk.ts

@@ -24,23 +24,32 @@ const generateUrl =
  * AWS_ACCESS_SECRET=[your-secret]
  */
 function getAwsConfig() {
-  const accessKeyId = env.AWS_ACCESS_KEY
   const bucket = env.S3_BUCKET
   const publicBucket = env.PUBLIC_S3_BUCKET
   const region = env.AWS_REGION
-  const secretAccessKey = env.AWS_ACCESS_SECRET
 
-  if (!accessKeyId || !secretAccessKey || !bucket || !publicBucket || !region) {
+  if (!bucket || !publicBucket || !region)
     throw new Error(
-      'AWS credentials not configured. Check you setup AWS_ACCESS_KEY, AWS_ACCESS_SECRET, (PUBLIC)_S3_BUCKET and AWS_REGION in your .env file.',
+      `Missing required AWS configuration variables: ${[!bucket && 'S3_BUCKET', !publicBucket && 'PUBLIC_S3_BUCKET', !region && 'AWS_REGION'].filter(Boolean).join(', ')}.`,
     )
+
+  const accessKeyId = env.AWS_ACCESS_KEY
+  const secretAccessKey = env.AWS_ACCESS_SECRET
+
+  if (accessKeyId && secretAccessKey) {
+    return {
+      region,
+      bucket,
+      publicBucket,
+      credentials: { accessKeyId, secretAccessKey },
+    }
   }
 
+  // If AWS_ACCESS_KEY and AWS_ACCESS_SECRET are not set, the SDK will use AWS IAM role.
   return {
     region,
     bucket,
     publicBucket,
-    credentials: { accessKeyId, secretAccessKey },
   }
 }