From e8eac2deb0133cdaffee9de5c9105862ad4c79fb Mon Sep 17 00:00:00 2001 From: Xinwei Xiong <3293172751NSS@gmail.com> Date: Wed, 14 May 2025 14:00:30 +0800 Subject: [PATCH] docs: update deployment guide and Docker setup documentation to use 'docker compose' syntax --- DEPLOYMENT_GUIDE.md | 24 +++++++++---------- DOCKER_SETUP.md | 24 +++++++++---------- .../content/docs/docker-installation.mdx | 2 +- 3 files changed, 25 insertions(+), 25 deletions(-) diff --git a/DEPLOYMENT_GUIDE.md b/DEPLOYMENT_GUIDE.md index ba3774a..e4cc86d 100644 --- a/DEPLOYMENT_GUIDE.md +++ b/DEPLOYMENT_GUIDE.md @@ -22,7 +22,7 @@ This mode runs everything: frontend, backend, database, and pgAdmin. It's ideal ```bash # Both files are automatically used (docker-compose.yml + docker-compose.override.yml) -docker-compose up -d +docker compose up -d ``` ### Core Services Mode (Production) @@ -31,7 +31,7 @@ This mode runs only the database and pgAdmin services. It's suitable for product ```bash # Explicitly use only the main file -docker-compose -f docker-compose.yml up -d +docker compose -f docker-compose.yml up -d ``` ## Custom Deployment Options @@ -42,13 +42,13 @@ You can specify which services to start by naming them: ```bash # Start only database -docker-compose up -d db +docker compose up -d db # Start database and pgAdmin -docker-compose up -d db pgadmin +docker compose up -d db pgadmin # Start only backend (requires db to be running) -docker-compose up -d backend +docker compose up -d backend ``` ### Using Custom Override Files @@ -57,7 +57,7 @@ You can create and use custom override files for different environments: ```bash # Create a staging configuration -docker-compose -f docker-compose.yml -f docker-compose.staging.yml up -d +docker compose -f docker-compose.yml -f docker-compose.staging.yml up -d ``` ## Environment Variables @@ -66,11 +66,11 @@ The deployment can be customized using environment variables: ```bash # Change default ports -FRONTEND_PORT=4000 BACKEND_PORT=9000 docker-compose up -d +FRONTEND_PORT=4000 BACKEND_PORT=9000 docker compose up -d # Or use a .env file # Create or modify .env file with your desired values -docker-compose up -d +docker compose up -d ``` ## Common Deployment Workflows @@ -90,17 +90,17 @@ cp surfsense_web/.env.example surfsense_web/.env # Edit the .env files with your configuration # Start full stack for development -docker-compose up -d +docker compose up -d ``` ### Database-Only Mode (for migrations or maintenance) ```bash # Start just the database -docker-compose -f docker-compose.yml up -d db +docker compose -f docker-compose.yml up -d db # Run migrations or maintenance tasks -docker-compose exec db psql -U postgres -d surfsense +docker compose exec db psql -U postgres -d surfsense ``` ### Scaling in Production @@ -116,7 +116,7 @@ This separation allows for better scaling and resource utilization in production If you encounter issues with the deployment: -- Check container logs: `docker-compose logs -f [service_name]` +- Check container logs: `docker compose logs -f [service_name]` - Ensure all required environment variables are set - Verify network connectivity between containers - Check that required ports are available and not blocked by firewalls diff --git a/DOCKER_SETUP.md b/DOCKER_SETUP.md index 892f974..6b7ee47 100644 --- a/DOCKER_SETUP.md +++ b/DOCKER_SETUP.md @@ -40,15 +40,15 @@ PGADMIN_DEFAULT_PASSWORD=surfsense SurfSense uses a flexible Docker Compose setup that allows you to choose between different deployment modes: -### Option 1: Full Stack Deployment (Development Mode) +### Option 1: Full-Stack Deployment (Development Mode) Includes frontend, backend, database, and pgAdmin. This is the default when running `docker compose up`. ### Option 2: Core Services Only (Production Mode) Includes only database and pgAdmin, suitable for production environments where you might deploy frontend/backend separately. Our setup uses two files: -- `docker compose.yml`: Contains core services (database and pgAdmin) -- `docker compose.override.yml`: Contains application services (frontend and backend) +- `docker-compose.yml`: Contains core services (database and pgAdmin) +- `docker-compose.override.yml`: Contains application services (frontend and backend) ## Setup @@ -68,7 +68,7 @@ Our setup uses two files: **Core Services Only (Production Mode)**: ```bash # Explicitly use only the main file - docker compose -f docker compose.yml up --build + docker compose -f docker-compose.yml up --build ``` 3. To run in detached mode (in the background): @@ -77,7 +77,7 @@ Our setup uses two files: docker compose up -d # Core services only - docker compose -f docker compose.yml up -d + docker compose -f docker-compose.yml up -d ``` 4. Access the applications: @@ -92,12 +92,12 @@ If you need to make temporary changes to either full stack or core services depl 1. **Temporarily disable override file**: ```bash - docker compose -f docker compose.yml up -d + docker compose -f docker-compose.yml up -d ``` 2. **Use a custom override file**: ```bash - docker compose -f docker compose.yml -f custom-override.yml up -d + docker compose -f docker-compose.yml -f custom-override.yml up -d ``` 3. **Temporarily modify which services start**: @@ -173,9 +173,9 @@ pgAdmin is a web-based administration tool for PostgreSQL. It is included in the ## 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 `.env` file or directly 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 you encounter frontend dependency errors, adjust the frontend's `Dockerfile` accordingly. - 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. - If you need only specific services, you can explicitly name them: `docker compose up db pgadmin` @@ -183,10 +183,10 @@ pgAdmin is a web-based administration tool for PostgreSQL. It is included in the The project uses Docker's default override mechanism: -1. **docker compose.yml**: Contains essential services (database and pgAdmin) -2. **docker compose.override.yml**: Contains development services (frontend and backend) +1. **docker-compose.yml**: Contains essential services (database and pgAdmin) +2. **docker-compose.override.yml**: Contains development services (frontend and backend) When you run `docker compose up` without additional flags, Docker automatically merges both files. -When you run `docker compose -f docker compose.yml up`, only the specified file is used. +When you run `docker compose -f docker-compose.yml up`, only the specified file is used. This approach lets you maintain a cleaner codebase without manually commenting/uncommenting services in your configuration files. diff --git a/surfsense_web/content/docs/docker-installation.mdx b/surfsense_web/content/docs/docker-installation.mdx index 07a691f..6dedaa9 100644 --- a/surfsense_web/content/docs/docker-installation.mdx +++ b/surfsense_web/content/docs/docker-installation.mdx @@ -218,7 +218,7 @@ pgAdmin is included in the Docker setup to help manage your PostgreSQL database. - **Linux/macOS:** If you encounter permission errors, you may need to run the docker commands with `sudo`. - **Windows:** If you see access denied errors, make sure you're running Command Prompt or PowerShell as Administrator. -- 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 `docker-compose.yml` file. - For backend dependency issues, check the `Dockerfile` in the backend directory. - For frontend dependency issues, check the `Dockerfile` in the frontend directory. - **Windows-specific:** If you encounter line ending issues (CRLF vs LF), configure Git to handle line endings properly with `git config --global core.autocrlf true` before cloning the repository.