vrr/SurfSense
2
0
Fork 0
mirror of https://github.com/MODSetter/SurfSense.git synced 2025-09-01 18:19:08 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: update deployment guide and Docker setup documentation to use 'docker compose' syntax

Browse source
This commit is contained in:
Xinwei Xiong 2025-05-14 14:00:30 +08:00
parent 6d591094cc
commit e8eac2deb0
3 changed files with 25 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
DEPLOYMENT_GUIDE.md
View file

@ -22,7 +22,7 @@ This mode runs everything: frontend, backend, database, and pgAdmin. It's ideal
```bash ```bash
# Both files are automatically used (docker-compose.yml + docker-compose.override.yml) # Both files are automatically used (docker-compose.yml + docker-compose.override.yml)
docker-compose up -d docker compose up -d
``` ```
### Core Services Mode (Production) ### Core Services Mode (Production)
@ -31,7 +31,7 @@ This mode runs only the database and pgAdmin services. It's suitable for product
```bash ```bash
# Explicitly use only the main file # 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 ## Custom Deployment Options
@ -42,13 +42,13 @@ You can specify which services to start by naming them:
```bash ```bash
# Start only database # Start only database
docker-compose up -d db docker compose up -d db
# Start database and pgAdmin # Start database and pgAdmin
docker-compose up -d db pgadmin docker compose up -d db pgadmin
# Start only backend (requires db to be running) # Start only backend (requires db to be running)
docker-compose up -d backend docker compose up -d backend
``` ```
### Using Custom Override Files ### Using Custom Override Files
@ -57,7 +57,7 @@ You can create and use custom override files for different environments:
```bash ```bash
# Create a staging configuration # 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 ## Environment Variables
@ -66,11 +66,11 @@ The deployment can be customized using environment variables:
```bash ```bash
# Change default ports # 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 # Or use a .env file
# Create or modify .env file with your desired values # Create or modify .env file with your desired values
docker-compose up -d docker compose up -d
``` ```
## Common Deployment Workflows ## Common Deployment Workflows
@ -90,17 +90,17 @@ cp surfsense_web/.env.example surfsense_web/.env
# Edit the .env files with your configuration # Edit the .env files with your configuration
# Start full stack for development # Start full stack for development
docker-compose up -d docker compose up -d
``` ```
### Database-Only Mode (for migrations or maintenance) ### Database-Only Mode (for migrations or maintenance)
```bash ```bash
# Start just the database # 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 # 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 ### 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: 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 - Ensure all required environment variables are set
- Verify network connectivity between containers - Verify network connectivity between containers
- Check that required ports are available and not blocked by firewalls - Check that required ports are available and not blocked by firewalls

24
DOCKER_SETUP.md
View file

@ -40,15 +40,15 @@ PGADMIN_DEFAULT_PASSWORD=surfsense
SurfSense uses a flexible Docker Compose setup that allows you to choose between different deployment modes: 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`. Includes frontend, backend, database, and pgAdmin. This is the default when running `docker compose up`.
### Option 2: Core Services Only (Production Mode) ### Option 2: Core Services Only (Production Mode)
Includes only database and pgAdmin, suitable for production environments where you might deploy frontend/backend separately. Includes only database and pgAdmin, suitable for production environments where you might deploy frontend/backend separately.
Our setup uses two files: Our setup uses two files:
- `docker compose.yml`: Contains core services (database and pgAdmin) - `docker-compose.yml`: Contains core services (database and pgAdmin)
- `docker compose.override.yml`: Contains application services (frontend and backend) - `docker-compose.override.yml`: Contains application services (frontend and backend)
## Setup ## Setup
@ -68,7 +68,7 @@ Our setup uses two files:
**Core Services Only (Production Mode)**: **Core Services Only (Production Mode)**:
```bash ```bash
# Explicitly use only the main file # 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): 3. To run in detached mode (in the background):
@ -77,7 +77,7 @@ Our setup uses two files:
docker compose up -d docker compose up -d
# Core services only # Core services only
docker compose -f docker compose.yml up -d docker compose -f docker-compose.yml up -d
``` ```
4. Access the applications: 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**: 1. **Temporarily disable override file**:
```bash ```bash
docker compose -f docker compose.yml up -d docker compose -f docker-compose.yml up -d
``` ```
2. **Use a custom override file**: 2. **Use a custom override file**:
```bash ```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**: 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 ## Troubleshooting
- If you encounter permission errors, you may need to run the docker commands with `sudo`. - 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 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 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` - 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: The project uses Docker's default override mechanism:
1. **docker compose.yml**: Contains essential services (database and pgAdmin) 1. **docker-compose.yml**: Contains essential services (database and pgAdmin)
2. **docker compose.override.yml**: Contains development services (frontend and backend) 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 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. This approach lets you maintain a cleaner codebase without manually commenting/uncommenting services in your configuration files.

2
surfsense_web/content/docs/docker-installation.mdx
View file

@ -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`. - **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. - **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 backend dependency issues, check the `Dockerfile` in the backend directory.
- For frontend dependency issues, check the `Dockerfile` in the frontend 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. - **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.