Skip to content
🌴 Palmr. - Documentation

Installation

Quick Start with Default Docker Compose

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:

Terminal window
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.

Ways to Execute the Startup Script

First of all, clone the official repository: https://github.com/kyantech/Palmr.git

There are two ways to execute the script:

To use this method, you need to have the make command installed on your machine.

To generate the new docker-compose.yml file using a Makefile, run the following command from the project root:

Terminal window
make gen-compose

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.

After the file is generated, you can modify or adapt it for deployment in other environments.

Running the Project

After generating the new docker-compose.yml file, you can start the project by running the following command from the project root:

Terminal window
docker compose up -d

To access Palmr. in a local environment, open your browser and visit:

http://localhost:4173

Deployment in Production

For production environments with high scalability and availability requirements, we recommend using Kubernetes, Docker Swarm, or a similar container orchestrator.

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:

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.

Running in Development Mode

If you want to modify the ports in a local environment and run the project using Docker with Docker Compose, we recommend using the docker-compose-dev.yaml file. This file builds the project based on the files in the cloned repository.

When using docker-compose-dev.yaml, make sure to configure all port and URL settings correctly. Incorrect configuration will prevent Palmr. from functioning as expected.

Docker Compose in Production Environments

We do not recommend using docker-compose.yml in production or VPS environments. Docker Compose is designed for development and testing purposes only, not for handling production workloads.

For production environments, we recommend using Kubernetes. However, the repository does not include a ready-to-use Kubernetes configuration, so you will need to configure it manually.

Alternatively, you can set up the application using separate services as follows:

  • Frontend: Host on Vercel or AWS Amplify.
  • Backend: Host on Render.com or similar services.
  • MinIO: Deploy separately on a server using Docker.
  • Database: Host on a managed service like Neon.tech.

Environment Variables

The Palmr. code is completely open-source, allowing you to adjust the deployment to meet your needs. Ensure that the environment variables are correctly configured to avoid issues during execution.

Additional Resources