mirror of
https://github.com/MODSetter/SurfSense.git
synced 2025-09-01 18:19:08 +00:00
docs: update deployment guide and Docker setup documentation to use 'docker compose' syntax
This commit is contained in:
parent
6d591094cc
commit
e8eac2deb0
3 changed files with 25 additions and 25 deletions
|
@ -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
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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.
|
||||
|
|
Loading…
Add table
Reference in a new issue