From b5ede457a4d01d201d5daa54f350dc1213a841a4 Mon Sep 17 00:00:00 2001 From: Xinwei Xiong <3293172751NSS@gmail.com> Date: Fri, 9 May 2025 16:18:05 +0800 Subject: [PATCH] enhance Docker setup documentation and configuration options --- .env.example | 17 ++++++++++++ DOCKER_SETUP.md | 68 +++++++++++++++++++++++++++++++++++++++++----- README.md | 13 ++++++++- docker-compose.yml | 31 +++++++++++++++------ 4 files changed, 112 insertions(+), 17 deletions(-) create mode 100644 .env.example diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..cc6ebe3 --- /dev/null +++ b/.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 diff --git a/DOCKER_SETUP.md b/DOCKER_SETUP.md index 44e6a14..7ad878c 100644 --- a/DOCKER_SETUP.md +++ b/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. diff --git a/README.md b/README.md index 213e1c1..e8979cf 100644 --- a/README.md +++ b/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 diff --git a/docker-compose.yml b/docker-compose.yml index 736400a..f8cfc25 100644 --- a/docker-compose.yml +++ b/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: \ No newline at end of file + postgres_data: + pgadmin_data: \ No newline at end of file