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)Manual Installation
Manual installation is a bit more complex and labor-intensive compared to installation via Docker Compose. However, by following this step-by-step guide, you can execute the project cleanly.
It's worth noting that even though our frontend and backend are run manually, we will still need to use Docker or another third-party service to run Postgres and MinIO. In this tutorial, we will use Docker with Docker Compose to set up MinIO and Postgres.
For this, within our apps/server directory, we already have a Docker Compose file that runs MinIO and Postgres, which are necessary for the application to function. However, feel free to use another service if you prefer. Once again, we are using Docker Compose to reduce the manual effort required to set up these services, especially third-party services like Postgres and MinIO.
Now, let's proceed with the step-by-step guide.
Prerequisites
Before we begin, we need to have the following tools installed in our environment:
- Docker
- Docker Compose
- Node.js
- pnpm
- Git
It's important to emphasize that the entire repository was written using the pnpm package manager. Therefore, it is highly recommended to use pnpm to run the services to avoid potential issues. However, if you prefer to use another package manager like npm, yarn, or bun, you may do so at your own risk. The system might work normally, but it could also present unknown and unmapped errors when using other package managers. So, we strongly recommend using pnpm.
Running the Application
Step 1: Clone the Repository
First, clone the official repository:
In the root of this repository, you will find a folder called apps. Inside this folder, there are three subfolders: docs, server, and web. For now, we are interested in the server and web folders, which contain our backend (written in Fastify) and frontend (written in React + Vite), respectively.
Step 2: Set Up Backend Services
Navigate to the backend folder, where the Docker Compose file for MinIO and Postgres is located:
Inside this folder, you can start by running:
This command will run Postgres and MinIO in the background. If you need to make any changes, the file being executed with docker compose up is located at apps/server/docker-compose.yaml. However, we recommend using the default settings for the first run and making changes only after you have a functional version of the base code.
Step 3: Set Up Backend
With MinIO and Postgres running via Docker Compose, let's proceed to the next steps, which involve running the project itself. Here, we will build and run the project in production mode, not development mode. To do this, we need to build both the backend and frontend applications.
Since we are already in the server folder, let's start with the backend.
3.1: Set Up Environment Variables
We need some environment variables for Palmr to run successfully. For this, we will use the .env.example file provided in the repository as a base.
Simply run:
This command copies the necessary environment variables to a .env file in the root directory.
3.2: Install Dependencies
Next, we need to initialize the database connected directly to Postgres via Prisma, our ORM. But for Prisma to work, we need to install the dependencies for our backend project. With Node and pnpm installed, run:
3.3: Generate Prisma Client
After the installation is complete, run the following command:
The prisma generate command generates the Prisma client for the project. This client allows programmatic access to the database.
3.4: Deploy Prisma Migrations
Once the generation is complete, run:
The prisma migrate deploy command deploys the Prisma migration.
3.5: Seed the Database
After the migration is deployed, we can seed the database to populate the initial tables with the following command:
Now, our database is ready for the project to run.
3.6: Build and Run the Backend
To run the backend, simply execute:
This command builds the application for production. After the build is complete, run:
Following these steps, the backend will be functional. To test it, you can access:
This is the API documentation page.
Step 4: Set Up Frontend
The frontend setup is similar to the backend, but we don't need to run any Docker containers—only the service itself.
4.1: Navigate to the Frontend Directory
If you are in the server folder:
If you are in the root of the repository:
4.2: Set Up Environment Variables
Once in the web directory, first run:
This populates the environment variables, just like in the backend.
4.3: Install Dependencies
Next, install the dependencies:
4.4: Build and Run the Frontend
Now, the process for the frontend is simpler. We can simply run the build with:
Once the build is complete, start the service with:
Wait for the service to start, and then you can test the entire application at:
Conclusion
That's it! This is the step-by-step guide to manually running a production version of Palmr.