Deprecated version documentation
This documentation refers to a previous version of Palmr. It may contain more complex configurations and bugs that have already been fixed.
View latest documentation (v3.0-beta)🐳 Installation (Docker Compose)
Installation via Docker Compose is the simplest way to run the project across different environments. For it to run correctly, we need two main tools installed in our environment:
- Docker (https://docs.docker.com)
- Docker Compose (https://docs.docker.com/compose)
It's worth emphasizing that Palmr. was fully developed in a MacOS environment and extensively tested on Linux servers. Therefore, we can guarantee the best system performance in these environments. Windows and other environments have not been tested yet, and potential bugs may occur during execution. However, remember that we are still in a beta version of Palmr., and errors or bugs can occur in any operating system. If you identify any issues, we appreciate your help in notifying us through our GitHub issues page.
⚡ Quick Start
Having installed Docker and Docker Compose in our environment, we can proceed with the simple installation using these tools.
In the root folder of our project, we can find our docker-compose.yaml
file, which is the only file needed to run the project via Docker and Docker Compose. This is because the pre-built images are already in our DockerHub and are only referenced in the docker-compose.yaml
Any changes needed for execution can be made directly in our docker-compose.yaml
or via environment variables, which we will show later in this tutorial.
Next, let's look at the content of our docker-compose.yaml
.
🐳 Docker Compose Content
Below is the complete content of our docker-compose.yaml
that can be copied directly from here or from our official repository (Docker Compose).
Notice that the docker-compose.yaml
has several comments that help you configure your own compose to meet your environment's needs. Let's give an overview of some changes we can make.
⚙️ Services Overview
Palmr. consists of four main services, each with specific responsibilities. Below, we present a detailed view of each component:
Service | Image | Exposed Ports | Main Features |
---|---|---|---|
palmr | kyantech/palmr:latest | 3333 (API) 5487 (Web) | • Combined backend API and frontend service • Depends on services: postgres and minio • Has healthcheck to ensure availability |
minio (Storage) | minio/minio:RELEASE.2025-03-12T18-04-18Z | 6421(API) 6422(Console) | • File storage service • Persistent volume for data |
minio-init (Config) | minio/mc:RELEASE.2025-03-12T17-29-24Z | N/A | • Initially configures the "files" bucket • Runs only once during initialization |
postgres (Database) | bitnami/postgresql:17.2.0 | 5432 | • PostgreSQL database • Persistent volume for data |
🛠️ Available Environment Variables
The table below shows all environment variables that can be set
Variable | Default Value | Description |
---|---|---|
API_INTERNAL_PORT | 3333 | Internal API port in container |
API_EXTERNAL_PORT | 3333 | Exposed port on host for API |
POSTGRES_PASSWORD | postgresRootPassword | PostgreSQL database password |
APP_EXTERNAL_PORT | 5487 | Exposed port on host for frontend |
APP_URL | http://localhost:5487 | Complete frontend URL |
SERVER_IP | localhost | IP of the server where the application is running |
MINIO_ROOT_USER | minio_root_user | MinIO admin user |
MINIO_ROOT_PASSWORD | minioRootPassword | MinIO admin password |
MINIO_INTERNAL_API_PORT | 6421 | Internal MinIO API port |
MINIO_INTERNAL_CONSOLE_PORT | 6422 | Internal MinIO console port |
MINIO_EXTERNAL_API_PORT | 6421 | Exposed port on host for MinIO API |
MINIO_EXTERNAL_CONSOLE_PORT | 6422 | Exposed port on host for MinIO console |
POSTGRESQL_USERNAME | postgres | PostgreSQL user |
POSTGRESQL_DATABASE | palmr_db | Database name |
MAX_FILESIZE | 1073741824 | Max Uploadsize per file. Unit in Bytes |
All these variables can be configured through a .env file in the project root or defined directly in the environment where docker-compose will be executed. The best way to do this is up to you. But be careful to replace correctly if doing directly in the compose instead of providing an environment var.
🗂️ Persistent Volumes
- minio_data: Stores MinIO files
- postgres_data: Stores PostgreSQL data
💻 Local Execution
In a localhost environment, there's no mystery. If you don't want to change any service exposure ports, you can simply run:
This will execute all necessary services and give you access to the following URLs (if you haven't changed any ports):
- Frontend: http://localhost:5487
- Backend: http://localhost:3333
- MinIO API: http://localhost:6421
- MinIO Console: http://localhost:6422
- Postgres Database: http://localhost:5432 (Connection only)
If you have changed any port, simply access the URL with the port you configured.
🌐 Production (VPS or other)
For production environments, whether it's your VPS, Homelab Server, or other, the execution is very similar to the localhost environment, except for some particularities that may occur in some cases.
We mainly need to pay attention to the following points:
- Correctly set the
SERVER_IP
env var with our server's IP, otherwise some redirects and queries will fail during App execution. - Set the
APP_URL
- regardless of whether the frontend is on the same server and with the same IP, it's extremely important to set this environment variable, otherwise sharing links will be generated incorrectly. - For all environment variables that are
PASSWORD
, it's highly recommended to generate secure passwords and replace them as env vars. - Lastly, make sure no docker service will conflict with any existing ones in your environment. If there is a conflict, simply change the execution ports via environment var or in the docker compose.
To generate a .env file with just the server_ip
configuration, you can run this command:
execute this command in your server terminal, at same path of docker-compose.yaml.
Basically, by paying attention to these points, you can quickly execute the project with the same command we used for localhost:
⚠️ This makes sure you're always running the latest beta version of the image, otherwise, Docker might reuse an outdated one from cache.
At this stage, if you encounter any errors, it's worth reviewing your docker-compose.yaml
and trying again, paying close attention to the points mentioned above.
First test without using reverse proxies like Caddy, Traefik, etc... if you plan to use them. Access the services via
server_ip:port
after confirming they work, then make the necessary routing configurations as desired.
If you haven't changed the execution ports, you'll have access on your server at:
- Frontend:
[server_ip]:5487
- Backend:
[server_ip]:3333
- MinIO API:
[server_ip]:6421
- MinIO Console:
[server_ip]:6422
- Postgres Database:
[server_ip]:5432
(Connection only)
If you've changed any port, simply access the URL with the port you configured.
It's worth noting that this is just a quick start and we're not going into details about any of the developed services, but it's recommended for execution in any environment. However, if your focus is on using Palmr. with high availability in mind, it's recommended to use a container orchestrator prepared for this, such as Kubernetes or similar, but we don't cover this type of configuration in our documentation.