feat: update Docker Compose files for improved configuration and documentation

- Refactored environment variable definitions in docker-compose files to enhance clarity and consistency. - Updated healthcheck commands to utilize dynamic port variables for better adaptability. - Added a new quick-start guide to the documentation, providing users with a streamlined setup process using Docker Compose. - Included the quick-start page in the meta.json for better navigation in the documentation.
2025-10-22 22:02:00 +00:00 · 2025-05-30 17:10:58 -03:00
parent 2276ed5bd6
commit 602780e8dd
5 changed files with 213 additions and 36 deletions
--- a/apps/docs/content/docs/2.1-beta/meta.json
+++ b/apps/docs/content/docs/2.1-beta/meta.json
@@ -6,8 +6,8 @@
  "pages": [
    "---Introduction---",
    "index",
+    "quick-start",
    "installation",
-    "manual-installation",
    "api",
    "---How to use Palmr.---",
    "manage-users",
--- a/apps/docs/content/docs/2.1-beta/quick-start.mdx
+++ b/apps/docs/content/docs/2.1-beta/quick-start.mdx
@@ -0,0 +1,152 @@
+---
+title: Quick Start (Docker Compose)
+icon: "Rocket"
+---
+
+Welcome to the quickest and easiest way to get <span className="font-bold" >Palmr.</span> up and running! Whether you're new to <span className="font-bold italic">self-hosting</span> or a seasoned pro, you'll be amazed at how simple it is to deploy your own secure <span className="font-bold italic">file sharing solution</span>.
+
+In just a few minutes, you'll have a powerful, user-friendly <span className="font-bold italic">file sharing platform</span> running on your <span className="font-bold italic">server</span> or <span className="font-bold italic">VPS</span>. We've designed this quick start guide to get you operational with minimal effort, using the built-in <span className="font-bold italic">file storage system</span> - perfect for most use cases!
+
+While Palmr. offers advanced installation options (like <span className="font-bold italic">manual installation</span> or using <span className="font-bold italic">Amazon S3-compatible external storage</span>), this guide focuses on the fastest path to success using <span className="font-bold italic">Docker Compose</span>. For those interested in more advanced setups, we have dedicated sections in our documentation covering these alternative installation methods.
+
+## Overview
+
+Installation via Docker Compose is the simplest way to run the project across different environments. For it to run correctly, we need two main tools installed in our environment:
+
+- Docker ([https://docs.docker.com](https://docs.docker.com/))
+- Docker Compose ([https://docs.docker.com/compose](https://docs.docker.com/compose/))
+
+> _It's worth emphasizing that Palmr. was fully developed in a MacOS environment and extensively tested on Linux servers. Therefore, we can guarantee the best system performance in these environments. Windows and other environments have not been tested yet, and potential bugs may occur during execution. However, remember that we are still in a beta version of Palmr., and errors or bugs can occur in any operating system. If you identify any issues, we appreciate your help in notifying us through our GitHub [issues page](https://github.com/kyantech/Palmr/issues)._
+
+## Docker Compose File
+
+Having installed [Docker](https://docs.docker.com/) and [Docker Compose](https://docs.docker.com/compose/) in our environment, we can proceed with the simple installation using these tools.
+
+In the root folder of our project, we can find some different composes files, we gonna use the `docker-compose-file-system.yaml` file, which is the only file needed to run the project via Docker and Docker Compose using the file system as storage. This is because the pre-built images are already in our [DockerHub](https://hub.docker.com/repositories/kyantech) and are only referenced in the `docker-compose-file-system.yaml`
+
+Any changes needed for execution can be made directly in our `docker-compose-file-system.yaml` or via environment variables, which we will show later in this tutorial.
+
+Next, let's look at the content of our `docker-compose-file-system.yaml`.
+
+## Docker Compose Content
+
+Below is the complete content of our `docker-compose-file-system.yaml` that can be copied directly from here or from our official repository ([Docker Compose](https://github.com/kyantech/Palmr/blob/main/docker-compose-file-system.yaml)).
+
+```yaml
+services:
+  palmr:
+    image: kyantech/palmr:latest # Make sure to use the correct version (latest) of the image
+    container_name: palmr-application
+    depends_on:
+      postgres:
+        condition: "service_healthy"
+    environment:
+      - ENABLE_S3=false # Set to 'false' to use local filesystem storage instead of S3/MinIO or true to use S3/MinIO in this case we are using filesystem storage
+      - ENCRYPTION_KEY=${ENCRYPTION_KEY:-change-this-key-in-production-min-32-chars} # Required for filesystem encryption (min 32 chars) CHANGE THIS KEY IN PRODUCTION
+      - DATABASE_URL=postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgresRootPassword}@postgres:${DB_EXTERNAL_PORT:-5432}/${POSTGRES_DB:-palmr_db}?schema=public # Database URL with configurable credentials through env vars
+      - FRONTEND_URL=http://palmr:${APP_EXTERNAL_PORT:-5487} # Frontend URL - Make sure to use the correct frontend URL, depends on where the frontend is running, its prepared for localhost, but you can change it to your frontend URL if needed
+      - API_BASE_URL=http://palmr:${API_EXTERNAL_PORT:-3333} # Using Docker service name for internal communication
+      - MAX_FILESIZE=${MAX_FILESIZE:-1073741824} # Max Filesize for upload - Declared in Bytes. Default is 1GB. can be changed by admin in the frontend.
+    ports:
+      - "${API_EXTERNAL_PORT:-3333}:3333" # Server port (default: 3333) can be overridden by env var
+      - "${APP_EXTERNAL_PORT:-5487}:5487" # Web port (default: 5487) can be overridden by env var
+    volumes:
+      - palmr_uploads:/app/server/uploads # Uploads folder for the application
+      - palmr_temp_chunks:/app/server/temp-chunks # Temp chunks folder for the application
+    networks:
+      - palmr-network # Network for the application to communicate with the database
+    restart: unless-stopped # Restart the container unless it is stopped
+    healthcheck:
+      test: [
+          "CMD",
+          "sh",
+          "-c",
+          "wget --no-verbose --tries=1 --spider http://palmr:3333/health && wget --no-verbose --tries=1 --spider http://palmr:5487",
+        ] # Healthcheck for the application
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 120s
+
+  postgres:
+    image: postgres:16-alpine # You can use any postgres version you prefer, but remember that some versions might not be compatible
+    container_name: palmr-database
+    environment:
+      - POSTGRES_USER=${POSTGRES_USER:-postgres} # PostgreSQL username (default: postgres) can be overridden by env var
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-postgresRootPassword} # PostgreSQL password (default: postgresRootPassword) can be overridden by env var
+      - POSTGRES_DB=${POSTGRES_DB:-palmr_db} # PostgreSQL database name (default: palmr_db) can be overridden by env var
+    volumes:
+      - postgres_data:/var/lib/postgresql/data # PostgreSQL data volume for the application
+    ports:
+      - "${DB_EXTERNAL_PORT:-5432}:5432" # PostgreSQL port (default: 5432) can be overridden by env var
+    networks:
+      - palmr-network # Network for the application to communicate with the database
+    restart: unless-stopped # Restart the container unless it is stopped
+    healthcheck:
+      test: [
+          "CMD",
+          "pg_isready",
+          "-U",
+          "${POSTGRES_USER:-postgres}",
+          "-d",
+          "${POSTGRES_DB:-palmr_db}",
+        ] # Healthcheck for the database
+      interval: 5s
+      timeout: 3s
+      retries: 6
+      start_period: 30s
+
+volumes:
+  postgres_data: # PostgreSQL data volume for the application referenced in the postgres service
+  palmr_uploads: # Uploads folder for the application referenced in the palmr service
+  palmr_temp_chunks: # Temp chunks folder for the application referenced in the palmr service
+
+networks:
+  palmr-network:
+    driver: bridge
+```
+
+Notice that the `docker-compose-file-system.yaml` has several comments that help you configure your own compose to meet your environment's needs. Let's give an overview of some changes we can make.
+
+---
+
+### ⚙️ Services Overview
+
+Palmr. consists of two main services for filesystem storage setup, each with specific responsibilities. Below, we present a detailed view of each component:
+
+| **Service**         | **Image**                                                                                | **Exposed Ports**                 | **Main Features**                                                                                                                                                 |
+| ------------------- | ---------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| palmr               | [kyantech/palmr:latest](https://hub.docker.com/repository/docker/kyantech/palmr/general) | **3333** (API)<br/>**5487** (Web) | • Combined backend API and frontend service<br/>• Uses local filesystem storage<br/>• Depends on PostgreSQL database<br/>• Has healthcheck to ensure availability |
+| postgres (Database) | [postgres:16-alpine](https://hub.docker.com/_/postgres)                                  | **5432**                          | • PostgreSQL database<br/>• Stores metadata and user data<br/>• Persistent volume for data<br/>• Alpine Linux based for smaller size                              |
+
+---
+
+### 🛠️ Available Environment Variables
+
+The table below shows all environment variables that can be set for the filesystem storage setup
+
+| **Variable**        | **Default Value**                          | **Description**                                              |
+| ------------------- | ------------------------------------------ | ------------------------------------------------------------ |
+| `ENABLE_S3`         | false                                      | Set to 'false' for filesystem storage or 'true' for S3/MinIO |
+| `ENCRYPTION_KEY`    | change-this-key-in-production-min-32-chars | Required for filesystem encryption (minimum 32 characters)   |
+| `API_EXTERNAL_PORT` | 3333                                       | Exposed port on host for API                                 |
+| `APP_EXTERNAL_PORT` | 5487                                       | Exposed port on host for frontend                            |
+| `DB_EXTERNAL_PORT`  | 5432                                       | Exposed port on host for PostgreSQL                          |
+| `POSTGRES_USER`     | postgres                                   | PostgreSQL username                                          |
+| `POSTGRES_PASSWORD` | postgresRootPassword                       | PostgreSQL password                                          |
+| `POSTGRES_DB`       | palmr_db                                   | PostgreSQL database name                                     |
+| `MAX_FILESIZE`      | 1073741824                                 | Max Uploadsize per file. Unit in Bytes (1GB default)         |
+
+> _All these variables can be configured through a .env file in the project root or defined directly in the environment where docker-compose will be executed. The ENCRYPTION_KEY is critical for filesystem storage security and MUST be changed in production environments._
+
+---
+
+#### 🗂️ Persistent Volumes
+
+- **postgres_data**: Stores PostgreSQL database files
+- **palmr_uploads**: Stores uploaded files in the filesystem
+- **palmr_temp_chunks**: Stores temporary file chunks during upload process
+
+#### 🌐 Network Configuration
+
+- **palmr-network**: Bridge network for inter-service communication between Palmr. and PostgreSQL
--- a/docker-compose-file-system.yaml
+++ b/docker-compose-file-system.yaml
@@ -13,15 +13,11 @@ services:
      # Server environment variables
      - DATABASE_URL=postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgresRootPassword}@postgres:${DB_EXTERNAL_PORT:-5432}/${POSTGRES_DB:-palmr_db}?schema=public # Database URL with configurable credentials through env vars
      - FRONTEND_URL=http://palmr:${APP_EXTERNAL_PORT:-5487} # Frontend URL - Make sure to use the correct frontend URL, depends on where the frontend is running, its prepared for localhost, but you can change it to your frontend URL if needed
-      - MAX_FILESIZE=${MAX_FILESIZE:-1073741824} # Max Filesize for upload - Declared in Bytes. Default is 1GiB. can be changed by admin in the frontend.
-
-      # Web environment variables
-      - NODE_ENV=production # Always set to production for better performance
-      - NEXT_TELEMETRY_DISABLED=1 # Disable telemetry for better performance
-      - API_BASE_URL=http://palmr:3333 # Using Docker service name for internal communication
+      - API_BASE_URL=http://palmr:${API_EXTERNAL_PORT:-3333} # Using Docker service name for internal communication
+      - MAX_FILESIZE=${MAX_FILESIZE:-1073741824} # Max Filesize for upload - Declared in Bytes. Default is 1GB. can be changed by admin in the frontend.
    ports:
-      - "${API_EXTERNAL_PORT:-3333}:3333"  # Server port (default: 3333) can be overridden by env var
-      - "${APP_EXTERNAL_PORT:-5487}:5487"  # Web port (default: 5487) can be overridden by env var
+      - "${API_EXTERNAL_PORT:-3333}:3333" # Server port (default: 3333) can be overridden by env var
+      - "${APP_EXTERNAL_PORT:-5487}:5487" # Web port (default: 5487) can be overridden by env var
    volumes:
      - palmr_uploads:/app/server/uploads # Uploads folder for the application
      - palmr_temp_chunks:/app/server/temp-chunks # Temp chunks folder for the application
@@ -29,7 +25,12 @@ services:
      - palmr-network # Network for the application to communicate with the database
    restart: unless-stopped
    healthcheck:
-      test: ["CMD", "sh", "-c", "wget --no-verbose --tries=1 --spider http://palmr:3333/health && wget --no-verbose --tries=1 --spider http://palmr:5487"] # Healthcheck for the application
+      test: [
+          "CMD",
+          "sh",
+          "-c",
+          "wget --no-verbose --tries=1 --spider http://palmr:${API_EXTERNAL_PORT:-3333}/health && wget --no-verbose --tries=1 --spider http://palmr:5487",
+        ] # Healthcheck for the application
      interval: 30s
      timeout: 10s
      retries: 5
@@ -43,14 +44,21 @@ services:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-postgresRootPassword} # PostgreSQL password (default: postgresRootPassword) can be overridden by env var
      - POSTGRES_DB=${POSTGRES_DB:-palmr_db} # PostgreSQL database name (default: palmr_db) can be overridden by env var
    volumes:
-      - postgres_data:/var/lib/postgresql/data # PostgreSQL data volume for the application 
+      - postgres_data:/var/lib/postgresql/data # PostgreSQL data volume for the application
    ports:
      - "${DB_EXTERNAL_PORT:-5432}:5432" # PostgreSQL port (default: 5432) can be overridden by env var
    networks:
      - palmr-network # Network for the application to communicate with the database
    restart: unless-stopped
    healthcheck:
-      test: ["CMD", "pg_isready", "-U", "${POSTGRES_USER:-postgres}", "-d", "${POSTGRES_DB:-palmr_db}"] # Healthcheck for the database
+      test: [
+          "CMD",
+          "pg_isready",
+          "-U",
+          "${POSTGRES_USER:-postgres}",
+          "-d",
+          "${POSTGRES_DB:-palmr_db}",
+        ] # Healthcheck for the database
      interval: 5s
      timeout: 3s
      retries: 6
@@ -63,4 +71,4 @@ volumes:

 networks:
  palmr-network:
-    driver: bridge
+    driver: bridge
--- a/docker-compose-s3-minio.yaml
+++ b/docker-compose-s3-minio.yaml
@@ -20,20 +20,22 @@ services:
      # Server environment variables
      - DATABASE_URL=postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgresRootPassword}@postgres:${DB_EXTERNAL_PORT:-5432}/${POSTGRES_DB:-palmr_db}?schema=public # Database URL with configurable credentials through env vars
      - FRONTEND_URL=http://palmr:${APP_EXTERNAL_PORT:-5487} # Frontend URL - Make sure to use the correct frontend URL, depends on where the frontend is running, its prepared for localhost, but you can change it to your frontend URL if needed
+      - API_BASE_URL=http://palmr:${API_EXTERNAL_PORT:-3333} # Using Docker service name for internal communication
      - MAX_FILESIZE=${MAX_FILESIZE:-1073741824} # Max Filesize for upload - Declared in Bytes. Default is 1GiB. can be changed by admin in the frontend.

-      # Web environment variables
-      - NODE_ENV=production # Always set to production for better performance
-      - NEXT_TELEMETRY_DISABLED=1 # Disable telemetry for better performance
-      - API_BASE_URL=http://palmr:3333 # Using Docker service name for internal communication
    ports:
-      - "${API_EXTERNAL_PORT:-3333}:3333"  # Server port (default: 3333) can be overridden by env var
-      - "${APP_EXTERNAL_PORT:-5487}:5487"  # Web port (default: 5487) can be overridden by env var
+      - "${API_EXTERNAL_PORT:-3333}:3333" # Server port (default: 3333) can be overridden by env var
+      - "${APP_EXTERNAL_PORT:-5487}:5487" # Web port (default: 5487) can be overridden by env var
    networks:
      - palmr-network # Network for the application to communicate with the database
    restart: unless-stopped
    healthcheck:
-      test: ["CMD", "sh", "-c", "wget --no-verbose --tries=1 --spider http://palmr:3333/health && wget --no-verbose --tries=1 --spider http://palmr:5487"] # Healthcheck for the application
+      test: [
+          "CMD",
+          "sh",
+          "-c",
+          "wget --no-verbose --tries=1 --spider http://palmr:${API_EXTERNAL_PORT:-3333}/health && wget --no-verbose --tries=1 --spider http://palmr:5487",
+        ] # Healthcheck for the application
      interval: 30s
      timeout: 10s
      retries: 5
@@ -47,14 +49,21 @@ services:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-postgresRootPassword} # PostgreSQL password (default: postgresRootPassword) can be overridden by env var
      - POSTGRES_DB=${POSTGRES_DB:-palmr_db} # PostgreSQL database name (default: palmr_db) can be overridden by env var
    volumes:
-      - postgres_data:/var/lib/postgresql/data # PostgreSQL data volume for the application 
+      - postgres_data:/var/lib/postgresql/data # PostgreSQL data volume for the application
    ports:
      - "${DB_EXTERNAL_PORT:-5432}:5432" # PostgreSQL port (default: 5432) can be overridden by env var
    networks:
      - palmr-network # Network for the application to communicate with the database
    restart: unless-stopped
    healthcheck:
-      test: ["CMD", "pg_isready", "-U", "${POSTGRES_USER:-postgres}", "-d", "${POSTGRES_DB:-palmr_db}"] # Healthcheck for the database
+      test: [
+          "CMD",
+          "pg_isready",
+          "-U",
+          "${POSTGRES_USER:-postgres}",
+          "-d",
+          "${POSTGRES_DB:-palmr_db}",
+        ] # Healthcheck for the database
      interval: 5s
      timeout: 3s
      retries: 6
@@ -65,4 +74,4 @@ volumes:

 networks:
  palmr-network:
-    driver: bridge
+    driver: bridge
--- a/docker-compose-s3.yaml
+++ b/docker-compose-s3.yaml
@@ -9,7 +9,7 @@ services:
      # S3 Configuration (only used when ENABLE_S3=true)
      - ENABLE_S3=true # Set to true to use S3 storage
      - S3_ENDPOINT=${S3_ENDPOINT} # S3 endpoint (you have to set this to the s3 endpoint of the s3 server) CHANGE THIS TO YOUR S3 ENDPOINT
-      - S3_USE_SSL=${S3_USE_SSL:-true} # Use ssl for the s3 server always true for s3 
+      - S3_USE_SSL=${S3_USE_SSL:-true} # Use ssl for the s3 server always true for s3
      - S3_ACCESS_KEY=${S3_ACCESS_KEY} # S3 access key (you have to generate this key in s3 server)
      - S3_SECRET_KEY=${S3_SECRET_KEY} # S3 secret key (you have to generate this key in s3 server)
      - S3_REGION=${S3_REGION:-us-east-1} # S3 region (us-east-1 is the default region) but it depends on your s3 server region
@@ -19,20 +19,21 @@ services:
      # Server environment variables
      - DATABASE_URL=postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgresRootPassword}@postgres:${DB_EXTERNAL_PORT:-5432}/${POSTGRES_DB:-palmr_db}?schema=public # Database URL with configurable credentials through env vars
      - FRONTEND_URL=http://palmr:${APP_EXTERNAL_PORT:-5487} # Frontend URL - Make sure to use the correct frontend URL, depends on where the frontend is running, its prepared for localhost, but you can change it to your frontend URL if needed
-      - MAX_FILESIZE=${MAX_FILESIZE:-1073741824} # Max Filesize for upload - Declared in Bytes. Default is 1GiB. can be changed by admin in the frontend.
-
-      # Web environment variables
-      - NODE_ENV=production # Always set to production for better performance
-      - NEXT_TELEMETRY_DISABLED=1 # Disable telemetry for better performance
-      - API_BASE_URL=http://palmr:3333 # Using Docker service name for internal communication
+      - API_BASE_URL=http://palmr:${API_EXTERNAL_PORT:-3333} # Using Docker service name for internal communication
+      - MAX_FILESIZE=${MAX_FILESIZE:-1073741824} # Max Filesize for upload - Declared in Bytes. Default is 1GB. can be changed by admin in the frontend.
    ports:
-      - "${API_EXTERNAL_PORT:-3333}:3333"  # Server port (default: 3333) can be overridden by env var
-      - "${APP_EXTERNAL_PORT:-5487}:5487"  # Web port (default: 5487) can be overridden by env var
+      - "${API_EXTERNAL_PORT:-3333}:3333" # Server port (default: 3333) can be overridden by env var
+      - "${APP_EXTERNAL_PORT:-5487}:5487" # Web port (default: 5487) can be overridden by env var
    networks:
      - palmr-network # Network for the application to communicate with the database
    restart: unless-stopped
    healthcheck:
-      test: ["CMD", "sh", "-c", "wget --no-verbose --tries=1 --spider http://palmr:3333/health && wget --no-verbose --tries=1 --spider http://palmr:5487"] # Healthcheck for the application
+      test: [
+          "CMD",
+          "sh",
+          "-c",
+          "wget --no-verbose --tries=1 --spider http://palmr:3333/health && wget --no-verbose --tries=1 --spider http://palmr:5487",
+        ] # Healthcheck for the application
      interval: 30s
      timeout: 10s
      retries: 5
@@ -46,14 +47,21 @@ services:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-postgresRootPassword} # PostgreSQL password (default: postgresRootPassword) can be overridden by env var
      - POSTGRES_DB=${POSTGRES_DB:-palmr_db} # PostgreSQL database name (default: palmr_db) can be overridden by env var
    volumes:
-      - postgres_data:/var/lib/postgresql/data # PostgreSQL data volume for the application 
+      - postgres_data:/var/lib/postgresql/data # PostgreSQL data volume for the application
    ports:
      - "${DB_EXTERNAL_PORT:-5432}:5432" # PostgreSQL port (default: 5432) can be overridden by env var
    networks:
      - palmr-network # Network for the application to communicate with the database
    restart: unless-stopped
    healthcheck:
-      test: ["CMD", "pg_isready", "-U", "${POSTGRES_USER:-postgres}", "-d", "${POSTGRES_DB:-palmr_db}"] # Healthcheck for the database
+      test: [
+          "CMD",
+          "pg_isready",
+          "-U",
+          "${POSTGRES_USER:-postgres}",
+          "-d",
+          "${POSTGRES_DB:-palmr_db}",
+        ] # Healthcheck for the database
      interval: 5s
      timeout: 3s
      retries: 6
@@ -64,4 +72,4 @@ volumes:

 networks:
  palmr-network:
-    driver: bridge
+    driver: bridge