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 (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 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
-- Database: surfsense
+5. Click "Save" to establish the connection
-
-You can connect to it using any PostgreSQL client.
 
 ## 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.
+- 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_USER=${POSTGRES_USER:-postgres}
-      - POSTGRES_PASSWORD=postgres
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-postgres}
-      - POSTGRES_DB=surfsense
+      - 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:
+  pgadmin_data: