Merge pull request #83 from cubxxw/feat/optimize-docker

feat: enhance Docker setup documentation and configuration options

.env.example

@@ -0,0 +1,17 @@
+# Frontend Configuration
+FRONTEND_PORT=3000
+NEXT_PUBLIC_API_URL=http://backend:8000
+
+# Backend Configuration
+BACKEND_PORT=8000
+
+# Database Configuration
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_DB=surfsense
+POSTGRES_PORT=5432
+
+# pgAdmin Configuration
+PGADMIN_PORT=5050
+PGADMIN_DEFAULT_EMAIL=admin@surfsense.com
+PGADMIN_DEFAULT_PASSWORD=surfsense

DOCKER_SETUP.md

@@ -7,11 +7,41 @@ This document explains how to run the SurfSense project using Docker Compose.
 - Docker and Docker Compose installed on your machine
 - Git (to clone the repository)
 
+## Environment Variables Configuration
+
+SurfSense Docker setup supports configuration through environment variables. You can set these variables in two ways:
+
+1. Create a `.env` file in the project root directory (copy from `.env.example`)
+2. Set environment variables directly in your shell before running Docker Compose
+
+The following environment variables are available:
+
+```
+# Frontend Configuration
+FRONTEND_PORT=3000
+NEXT_PUBLIC_API_URL=http://backend:8000
+
+# Backend Configuration
+BACKEND_PORT=8000
+
+# Database Configuration
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_DB=surfsense
+POSTGRES_PORT=5432
+
+# pgAdmin Configuration
+PGADMIN_PORT=5050
+PGADMIN_DEFAULT_EMAIL=admin@surfsense.com
+PGADMIN_DEFAULT_PASSWORD=surfsense
+```
+
 ## Setup
 
 1. Make sure you have all the necessary environment variables set up:
    - Copy `surfsense_backend/.env.example` to `surfsense_backend/.env` and fill in the required values
    - Copy `surfsense_web/.env.example` to `surfsense_web/.env` and fill in the required values
+   - Optionally: Copy `.env.example` to `.env` in the project root to customize Docker settings
 
 2. Build and start the containers:
    ```bash
@@ -27,6 +57,7 @@ This document explains how to run the SurfSense project using Docker Compose.
    - Frontend: http://localhost:3000
    - Backend API: http://localhost:8000
    - API Documentation: http://localhost:8000/docs
+   - pgAdmin: http://localhost:5050
 
 ## Useful Commands
 
@@ -44,6 +75,7 @@ This document explains how to run the SurfSense project using Docker Compose.
   docker-compose logs -f backend
   docker-compose logs -f frontend
   docker-compose logs -f db
+  docker-compose logs -f pgadmin
   ```
 
 - Restart a specific service:
@@ -64,16 +96,38 @@ This document explains how to run the SurfSense project using Docker Compose.
 
 The PostgreSQL database with pgvector extensions is available at:
 - Host: localhost
-- Port: 5432
-- Username: postgres
-- Password: postgres
-- Database: surfsense
+- Port: 5432 (configurable via POSTGRES_PORT)
+- Username: postgres (configurable via POSTGRES_USER)
+- Password: postgres (configurable via POSTGRES_PASSWORD)
+- Database: surfsense (configurable via POSTGRES_DB)
 
-You can connect to it using any PostgreSQL client.
+You can connect to it using any PostgreSQL client or the included pgAdmin.
+
+## pgAdmin
+
+pgAdmin is a web-based administration tool for PostgreSQL. It is included in the Docker setup for easier database management.
+
+- URL: http://localhost:5050 (configurable via PGADMIN_PORT)
+- Default Email: admin@surfsense.com (configurable via PGADMIN_DEFAULT_EMAIL)
+- Default Password: surfsense (configurable via PGADMIN_DEFAULT_PASSWORD)
+
+### Connecting to the Database in pgAdmin
+
+1. Log in to pgAdmin using the credentials above
+2. Right-click on "Servers" in the left sidebar and select "Create" > "Server"
+3. In the "General" tab, give your connection a name (e.g., "SurfSense DB")
+4. In the "Connection" tab, enter the following:
+   - Host: db
+   - Port: 5432
+   - Maintenance database: surfsense
+   - Username: postgres 
+   - Password: postgres
+5. Click "Save" to establish the connection
 
 ## Troubleshooting
 
 - If you encounter permission errors, you may need to run the docker commands with `sudo`.
-- If ports are already in use, modify the port mappings in the `docker-compose.yml` file.
+- If ports are already in use, modify the port mappings in the `.env` file or directly in the `docker-compose.yml` file.
 - For backend dependency issues, you may need to modify the `Dockerfile` in the backend directory.
-- For frontend dependency issues, you may need to modify the `Dockerfile` in the frontend directory. 
+- For frontend dependency issues, you may need to modify the `Dockerfile` in the frontend directory.
+- If pgAdmin doesn't connect to the database, ensure you're using `db` as the hostname, not `localhost`, as that's the Docker network name. 

README.md

@@ -85,7 +85,10 @@ Join the [SurfSense Discord](https://discord.gg/ejRNvftDp9) and help shape the f
 
 SurfSense provides two installation methods:
 
-1. **[Docker Installation](https://www.surfsense.net/docs/docker-installation)** - The easiest way to get SurfSense up and running with all dependencies containerized. Less Customization.
+1. **[Docker Installation](https://www.surfsense.net/docs/docker-installation)** - The easiest way to get SurfSense up and running with all dependencies containerized.
+   - Includes pgAdmin for database management through a web UI
+   - Supports environment variable customization via `.env` file
+   - See [Docker Setup Guide](DOCKER_SETUP.md) for detailed instructions
 
 2. **[Manual Installation (Recommended)](https://www.surfsense.net/docs/manual-installation)** - For users who prefer more control over their setup or need to customize their deployment.
 
@@ -191,6 +194,14 @@ Before installation, make sure to complete the [prerequisite setup steps](https:
 -  **@tanstack/react-table**: Headless UI for building powerful tables & datagrids.
 
 
+ ### **DevOps**
+
+-  **Docker**: Container platform for consistent deployment across environments
+  
+-  **Docker Compose**: Tool for defining and running multi-container Docker applications
+
+-  **pgAdmin**: Web-based PostgreSQL administration tool included in Docker setup
+
 
 ### **Extension** 
  Manifest v3 on Plasmo

docker-compose.yml

@@ -6,21 +6,21 @@ services:
       context: ./surfsense_web
       dockerfile: Dockerfile
     ports:
-      - "3000:3000"
+      - "${FRONTEND_PORT:-3000}:3000"
     volumes:
       - ./surfsense_web:/app
       - /app/node_modules
     depends_on:
       - backend
     environment:
-      - NEXT_PUBLIC_API_URL=http://backend:8000
+      - NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL:-http://backend:8000}
 
   backend:
     build:
       context: ./surfsense_backend
       dockerfile: Dockerfile
     ports:
-      - "8000:8000"
+      - "${BACKEND_PORT:-8000}:8000"
     volumes:
       - ./surfsense_backend:/app
     depends_on:
@@ -28,7 +28,7 @@ services:
     env_file:
       - ./surfsense_backend/.env
     environment:
-      - DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/surfsense
+      - DATABASE_URL=postgresql+asyncpg://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgres}@db:5432/${POSTGRES_DB:-surfsense}
       - PYTHONPATH=/app
       - UVICORN_LOOP=asyncio
       - UNSTRUCTURED_HAS_PATCHED_LOOP=1
@@ -36,13 +36,26 @@ services:
   db:
     image: ankane/pgvector:latest
     ports:
-      - "5432:5432"
+      - "${POSTGRES_PORT:-5432}:5432"
     volumes:
       - postgres_data:/var/lib/postgresql/data
     environment:
-      - POSTGRES_USER=postgres
-      - POSTGRES_PASSWORD=postgres
-      - POSTGRES_DB=surfsense
+      - POSTGRES_USER=${POSTGRES_USER:-postgres}
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-postgres}
+      - POSTGRES_DB=${POSTGRES_DB:-surfsense}
+
+  pgadmin:
+    image: dpage/pgadmin4
+    ports:
+      - "${PGADMIN_PORT:-5050}:80"
+    environment:
+      - PGADMIN_DEFAULT_EMAIL=${PGADMIN_DEFAULT_EMAIL:-admin@surfsense.com}
+      - PGADMIN_DEFAULT_PASSWORD=${PGADMIN_DEFAULT_PASSWORD:-surfsense}
+    volumes:
+      - pgadmin_data:/var/lib/pgadmin
+    depends_on:
+      - db
 
 volumes:
-  postgres_data: 
+  postgres_data:
+  pgadmin_data: 

surfsense_web/content/docs/docker-installation.mdx

@@ -40,6 +40,7 @@ Before you begin, ensure you have:
     # Copy example environment files
     cp surfsense_backend/.env.example surfsense_backend/.env
     cp surfsense_web/.env.example surfsense_web/.env
+    cp .env.example .env  # For Docker-specific settings
     ```
 
     **Windows (Command Prompt):**
@@ -47,6 +48,7 @@ Before you begin, ensure you have:
     ```cmd
     copy surfsense_backend\.env.example surfsense_backend\.env
     copy surfsense_web\.env.example surfsense_web\.env
+    copy .env.example .env
     ```
 
     **Windows (PowerShell):**
@@ -54,9 +56,25 @@ Before you begin, ensure you have:
     ```powershell
     Copy-Item -Path surfsense_backend\.env.example -Destination surfsense_backend\.env
     Copy-Item -Path surfsense_web\.env.example -Destination surfsense_web\.env
+    Copy-Item -Path .env.example -Destination .env
     ```
 
-    Edit both `.env` files and fill in the required values:
+    Edit all `.env` files and fill in the required values:
+
+### Docker-Specific Environment Variables
+
+| ENV VARIABLE               | DESCRIPTION                                                                 | DEFAULT VALUE       |
+|----------------------------|-----------------------------------------------------------------------------|---------------------|
+| FRONTEND_PORT              | Port for the frontend service                                               | 3000                |
+| BACKEND_PORT               | Port for the backend API service                                            | 8000                |
+| POSTGRES_PORT              | Port for the PostgreSQL database                                            | 5432                |
+| PGADMIN_PORT               | Port for pgAdmin web interface                                              | 5050                |
+| POSTGRES_USER              | PostgreSQL username                                                         | postgres            |
+| POSTGRES_PASSWORD          | PostgreSQL password                                                         | postgres            |
+| POSTGRES_DB                | PostgreSQL database name                                                    | surfsense           |
+| PGADMIN_DEFAULT_EMAIL      | Email for pgAdmin login                                                     | admin@surfsense.com |
+| PGADMIN_DEFAULT_PASSWORD   | Password for pgAdmin login                                                  | surfsense           |
+| NEXT_PUBLIC_API_URL        | URL of the backend API (used by frontend)                                   | http://backend:8000 |
 
 **Backend Environment Variables:**
 
@@ -132,6 +150,23 @@ For other LLM providers, refer to the [LiteLLM documentation](https://docs.litel
    - Frontend: [http://localhost:3000](http://localhost:3000)
    - Backend API: [http://localhost:8000](http://localhost:8000)
    - API Documentation: [http://localhost:8000/docs](http://localhost:8000/docs)
+   - pgAdmin: [http://localhost:5050](http://localhost:5050)
+
+## Using pgAdmin
+
+pgAdmin is included in the Docker setup to help manage your PostgreSQL database. To connect:
+
+1. Open pgAdmin at [http://localhost:5050](http://localhost:5050)
+2. Login with the credentials from your `.env` file (default: admin@surfsense.com / surfsense)
+3. Right-click "Servers" > "Create" > "Server"
+4. In the "General" tab, name your connection (e.g., "SurfSense DB")
+5. In the "Connection" tab:
+   - Host: `db`
+   - Port: `5432`
+   - Maintenance database: `surfsense`
+   - Username: `postgres` (or your custom POSTGRES_USER)
+   - Password: `postgres` (or your custom POSTGRES_PASSWORD)
+6. Click "Save" to connect
 
 ## Useful Docker Commands