docs: update installation guide with security and deployment details

Add a new section "Quick Start with Default Docker Compose" to emphasize the risks of using default credentials and provide recommendations for secure deployment. Clarify the usage of Docker Compose for different environments (local, production) and update port configuration recommendations with a warning about ReactJS limitations.
This commit is contained in:
Daniel Luiz Alves
2025-04-04 00:40:49 -03:00
parent 68d6fd09af
commit fcaef88850

View File

@@ -5,9 +5,23 @@ description: Guide to install and run Palmr using Docker Compose
import { Tabs, TabItem } from '@astrojs/starlight/components';
### Startup Script for Docker Compose
### Quick Start with Default Docker Compose
To simplify the execution of the project and enable it to run on any machine, a **startup script** for Docker Compose was created. This script automates the generation of secure credentials and facilitates local setup.
There is a default `docker-compose.yml` file in the project root that can be used for quick execution. While this provides a convenient way to get started, it's important to note that using the default passwords is **not secure**, especially if the application is exposed to public networks. Malicious users could potentially exploit known default credentials to attack your deployment.
This base Docker Compose configuration works perfectly for localhost development but may require modifications when deployed to a VPS or production environment for optimal performance and security. Please consult the complete documentation for proper production deployment configurations.
For a quick start using the default configuration, simply run:
```bash
docker compose up -d
```
This command will start the project using the default configuration.
> ⚠️ **Important:** We strongly recommend testing your configuration locally first, especially if you've made any modifications to the Docker Compose files. Only after confirming everything works as expected locally should you proceed with deployment to a VPS or server environment.
### Startup Script for Docker Compose
To simplify the execution of the project and enable it to run on any machine, a **startup script** for Docker Compose was created. This script automates the generation of secure credentials and facilitates local setup. While this method provides better security than using default passwords, for maximum security, we strongly recommend moving all sensitive credentials to environment variables instead.
To execute the project using this approach, you need to have **Docker** and **Docker Compose** installed on your machine. While this is the simplest way to execute the project, it is **not recommended for production environments**.
@@ -23,13 +37,13 @@ There are two ways to execute the script:
<TabItem label="1. Using a Makefile">
To use this method, you need to have the `make` command installed on your machine.
To generate the `docker-compose.yml` file using a Makefile, run the following command from the project root:
To generate the new `docker-compose.yml` file using a Makefile, run the following command from the project root:
```bash
make gen-compose
```
This command will generate a `docker-compose.yml` file in the root of the project.
This command will subcribe the `docker-compose.yml` file in the root of the project.
- The script's primary function is to generate secure passwords for **MinIO** (object storage) and **Postgres** (database).
- The generated `docker-compose.yml` file serves as a base and can be modified at any time.
- It is configured to run locally via `localhost` and is **not intended for production** or VPS environments.
@@ -51,7 +65,7 @@ There are two ways to execute the script:
---
### Running the Project
After generating the `docker-compose.yml` file, you can start the project by running the following command from the project root:
After generating the new `docker-compose.yml` file, you can start the project by running the following command from the project root:
```bash
docker compose up -d
@@ -64,9 +78,9 @@ To access Palmr. in a local environment, open your browser and visit:
---
### Deployment in Production
For production environments, we recommend using **Kubernetes**, **Docker Swarm**, or a similar container orchestrator.
For production environments with high scalability and availability requirements, we recommend using **Kubernetes**, **Docker Swarm**, or a similar container orchestrator.
For local execution or testing environments, you can use Docker Compose with the `docker-compose.yml` file. This file pulls the latest Palmr. images from Docker and makes them available on specific ports, as shown below:
For homelab, personal projects, or environments where high availability and scalability are not critical, Docker Compose can be used without issues. The `docker-compose.yml` file pulls the latest Palmr. images from Docker and makes them available on specific ports, as shown below:
- **Frontend:** [http://localhost:4173](http://localhost:4173)
- **Backend:** [http://localhost:3333](http://localhost:3333)
@@ -79,7 +93,7 @@ For local execution or testing environments, you can use Docker Compose with the
### Port Configuration Recommendations
In this version of `docker-compose.yml`, none of the ports for the frontend and backend should be modified. Consequently, none of the URLs should be changed because the frontend image contains a pre-built version configured to work on port **4173**.
Due to technical limitations related to **ReactJS**, environment variables executed at runtime cannot be changed. Therefore, to ensure that the system functions correctly as designed, keep the `docker-compose.yml` file unchanged.
> ⚠️ Due to technical limitations related to **ReactJS**, environment variables executed at runtime cannot be changed. Therefore, to ensure that the system functions correctly as designed, keep the `docker-compose.yml` file unchanged.
---