Palmr/apps/docs/content/docs/2.0.0-beta/manual-installation.mdx

---
title: 📦 Manual Installation
---

Manual installation requires more detailed attention and hands-on configuration compared to the streamlined process offered by Docker Compose. While this approach demands additional effort and technical understanding, following our comprehensive step-by-step guide will ensure a clean and successful project execution with full control over each component.

An important consideration in this manual setup process is that while we'll be handling the frontend and backend deployments directly, we still require Docker or an equivalent third-party service to manage our Postgres database and MinIO object storage infrastructure. For the purposes of this tutorial, we've chosen to utilize Docker with Docker Compose to establish and configure both MinIO and Postgres, as this provides a reliable and well-tested environment.

To facilitate this setup, we've included a pre-configured Docker Compose file within the `apps/server` directory that handles the initialization and configuration of both MinIO and Postgres - two essential components for the application's core functionality. While this is our recommended approach, you maintain the flexibility to implement alternative solutions that better suit your specific needs or infrastructure requirements. Our decision to leverage Docker Compose for these particular services stems from its ability to significantly streamline the configuration process, especially when dealing with complex third-party services like Postgres and MinIO.

Should you be interested in exploring alternative deployment methods for hosting MinIO and Postgres without utilizing Docker and Docker Compose, comprehensive information is available through their respective official channels and documentation:

- MinIO GitHub: [Visit MinIO GitHub](https://github.com/minio/minio)
- Postgres Github: [Visit Postgres GitHub](https://github.com/postgres/postgres)
- MinIO documentation: [View MinIO docs](https://min.io/docs/minio/linux/index.html)
- Postgres documentation: [View Postgres docs](https://www.postgresql.org/docs/)

With these foundational concepts established, we can now proceed with our detailed, step-by-step installation guide.

---

## ✅ Prerequisites

Before proceeding with the installation, it's essential to ensure that your development environment is properly configured with all the necessary tools and dependencies. Please verify that you have the following software components installed and properly configured on your system:

- <span style={{ color: "#16a34a" }}>Docker</span> *(Required only if you plan to use Docker + Docker Compose)*
- <span style={{ color: "#16a34a" }}>Docker Compose</span> *(Required only if you plan to use Docker + Docker Compose)*
- <span style={{ color: "#16a34a" }}>Node.js</span> *(Essential for running JavaScript/TypeScript applications)*
- <span style={{ color: "#16a34a" }}>pnpm</span> *(Our preferred package manager)*
- <span style={{ color: "#16a34a" }}>Git</span> *(For version control and repository management)*

⚠️ <strong>A critical note regarding package management:</strong> This repository has been specifically developed and thoroughly tested using the pnpm package manager. While technically possible to use alternative package managers such as `npm`, `yarn`, or `bun`, we strongly advise against this approach.


---

## Running the Application

### 📥 Clone the Repository

To begin the installation process, you'll need to obtain a local copy of the codebase. Start by cloning the official repository using the following Git command:

```bash
git clone https://github.com/kyantech/Palmr.git
```

Upon successful cloning, you'll find yourself with a new directory containing the project structure. Within this directory, there's a crucial folder named 'apps' that houses three essential components: docs, server, and web. For the purposes of this installation guide, we'll focus primarily on the server and web directories, which contain our robust backend infrastructure (built with Fastify) and our responsive frontend application (developed using React + Vite), respectively.

---

### ⚙️ Set Up Backend Services

The next phase involves setting up our backend services. First, navigate to the backend directory where you'll find the Docker Compose configuration file for our essential services - MinIO and Postgres:

```bash
cd ./apps/server
```

Once you're in the correct directory, initiate the services by executing the following command:

```bash
docker compose up -d
```

This command initializes both Postgres and MinIO services in detached mode, allowing them to run seamlessly in the background. While the configuration file at `apps/server/docker-compose.yaml` can be customized to suit specific needs, we strongly recommend maintaining the default configuration for your initial setup. This approach ensures a smooth installation process, and you can always refine the settings once you have a working implementation.

Now that our essential services are operational through Docker Compose, we can proceed with the core backend setup. During this phase, we'll be preparing the application for production deployment rather than development mode. This process requires careful attention to both the backend and frontend components.

Since our current working directory is already set to the server folder, let's begin with the backend configuration.

#### 🔑 Set Up Environment Variables

A crucial preliminary step is configuring the environment variables that Palmr requires for proper operation. We've provided a template file named `.env.example` in the repository to streamline this process.

Execute this straightforward command to create your environment configuration:

```bash
cp .env.example .env
```

This operation creates a new `.env` file in the root directory, populated with all the necessary environmental configurations.

#### 📦 Install Dependencies

The next crucial step involves initializing our database connection through Prisma, our chosen Object-Relational Mapping (ORM) tool. However, before we can utilize Prisma effectively, we need to ensure all backend dependencies are properly installed. With your Node.js environment and pnpm package manager ready, execute:

```bash
pnpm install
```

#### ⚡ Generate Prisma Client

After successfully installing all dependencies, proceed with generating the Prisma client by running:

```bash
pnpm dlx prisma generate
```

This essential command generates the Prisma client specifically tailored for our project, establishing the necessary interface for seamless database interactions and operations.

#### 🔄 Deploy Prisma Migrations

With the client generation complete, deploy the database schema using:

```bash
pnpm dlx prisma migrate deploy
```

This command ensures all your database migrations are properly implemented, establishing the required database structure.

#### 🌱 Seed the Database

Following the successful migration deployment, we'll populate the database with initial data using our seeding script. Execute:

```bash
pnpm db:seed
```

This process will populate your database with the necessary initial data, preparing it for application use.

#### 🏗️ Build and Run the Backend

With all preparatory steps completed, we can now build the backend application:

```bash
pnpm run build
```

Once the build process successfully concludes, start the backend service:

```bash
pnpm start
```

To verify that your backend is functioning correctly, you can access the comprehensive API documentation at:

```bash
http://localhost:3333/docs
```

This documentation interface provides detailed information about all available API endpoints and their usage.

---

### 🎨 Set Up Frontend

The frontend configuration process follows a similar pattern to the backend setup, though it's somewhat simplified as it doesn't require Docker container management - we'll only need to configure and run the service itself.

#### 📂 Navigate to the Frontend Directory

If your current location is the server directory, use:

```bash
cd ../web
```

Alternatively, if you're starting from the repository root, navigate with:

```bash
cd apps/web
```

#### ⚙️ Set Up Environment Variables

After reaching the web directory, begin by creating your frontend environment configuration:

```bash
cp .env.example .env
```

This step mirrors our backend environment setup, ensuring all necessary variables are properly configured.

#### 📦 Install Dependencies

Proceed with installing all required frontend dependencies:

```bash
pnpm install
```

#### 💻 Build and Run the Frontend

The final stage of our frontend setup is straightforward. First, create a production build:

```bash
pnpm run build
```

After the build completes successfully, launch the frontend service:

```bash
pnpm serve
```

Once the service initialization is complete, you can access the full application through your web browser at:

```bash
http://localhost:3000
```

---

## 🎉 Conclusion

Congratulations! You've successfully completed the comprehensive setup process for deploying a production-ready instance of Palmr. This detailed guide has walked you through each crucial step, from initial repository cloning to final application deployment.

## 🔗 Useful Links

- [Docker Documentation](https://docs.docker.com/)
- [Node.js Documentation](https://nodejs.org/en/docs/)
- [pnpm Documentation](https://pnpm.io/)
- [Prisma Documentation](https://www.prisma.io/docs/)