---
title: Manual Installation
icon: Cog
---

Hey there! Looking to run **Palmr.** your way, with complete control over every piece of the stack? This manual installation guide is for you. No Docker, no pre-built containers just the raw source code to tweak, customize, and deploy as you see fit.

> **Prefer a quicker setup?** If this hands-on approach feels like overkill, check out our [**Quick Start (Docker)**](/docs/3.2-beta/quick-start) guide for a fast, containerized deployment. This manual path is tailored for developers who want to dive deep, modify the codebase, or integrate custom services.

Here's what you'll do at a glance:

1. **Clone** the repository to get the code.
2. **Configure** `.env` files for backend and frontend.
3. **Install** JavaScript dependencies using `pnpm`.
4. **Generate** the Prisma client and run database migrations.
5. **Seed** the database with initial Palmr. data.
6. **Build & start** the backend (Fastify API).
7. **Build & serve** the frontend (Next.js app).

We've broken down each step below feel free to jump to the section you're working on!

## Before you start

Let's make sure your environment is ready to roll. Check that you've got these tools installed and set up on your system:

- <span style={{ color: "#16a34a" }}>Node.js</span> *(Powers our JavaScript/TypeScript apps)*
- <span style={{ color: "#16a34a" }}>pnpm</span> *(Our go-to package manager)*
- <span style={{ color: "#16a34a" }}>Git</span> *(For cloning and managing the repo)*

⚠️ **Heads Up on Package Managers**: Palmr. was built and tested with `pnpm`. While you _could_ try `npm`, `yarn`, or `bun`, we strongly recommend sticking with `pnpm` to avoid compatibility headaches.

---

### System requirements

- **Operating System**: MacOS or Linux (recommended for best results)
  - Windows works but hasn't been thoroughly tested.
- **Memory**: At least 4GB RAM is suggested.
- **Storage**: Depends on how much file storage you'll need.
- **CPU**: 2+ cores for smooth performance.

---

## Let's Get Palmr. Running

### Step 1: Clone the repository

First things first, grab a local copy of the Palmr. codebase. Run this command to clone the official repo:

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

Once it's done, you'll have a new directory with the project structure. Inside, the `apps` folder holds the key pieces: `docs`, `server`, and `web`. For this guide, we're focusing on `server` (our Fastify backend) and `web` (our Next.js frontend).

---

### Step 2: Set up the backend

Let's get the backend up and running. Start by navigating to the server directory:

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

#### Configure environment variables

Before anything else, we need to set up the environment variables Palmr. relies on. We've included a handy template file called `.env.example` to get you started. Create your own `.env` file with this command:

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

This copies the template into a new `.env` file with all the necessary settings. Open it up if you need to tweak anything specific to your setup.

#### Install dependencies

Next, let's install the backend dependencies. With Node.js and `pnpm` ready, run:

```bash
pnpm install
```

This pulls in everything needed for the backend, including Prisma, our database ORM.

#### Generate Prisma client

Now, generate the Prisma client tailored for Palmr. with:

```bash
pnpm dlx prisma generate
```

This sets up the interface for smooth database interactions.

#### Deploy Prisma migrations

With the client ready, apply the database schema using:

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

This ensures your database structure is set up with all the required migrations.

#### Seed the database

Let's populate the database with some initial data. Run the seeding script:

```bash
pnpm db:seed
```

This adds the baseline data Palmr. needs to function properly.

#### Build and run the backend

Finally, build the backend app:

```bash
pnpm run build
```

Once the build is complete, start the service:

```bash
pnpm start
```

To confirm everything's working, check out the API documentation at:

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

This page lists all available API endpoints and how to use them.

---

### Step 3: Set up the frontend

With the backend humming, let's tackle the frontend setup.

#### Navigate to the Frontend Directory

If you're in the `server` folder, move to `web` with:

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

Or, from the repo root, use:

```bash
cd apps/web
```

#### Configure environment variables

Just like the backend, set up the frontend environment variables:

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

This creates a `.env` file with the necessary configurations for the frontend.

##### Upload Configuration

Palmr. supports configurable chunked uploading for large files. You can customize the chunk size by setting the following environment variable in your `.env` file:

```bash
NEXT_PUBLIC_UPLOAD_CHUNK_SIZE_MB=100
```

**How it works:**

- If `NEXT_PUBLIC_UPLOAD_CHUNK_SIZE_MB` is set, Palmr. will use this value (in megabytes) as the chunk size for all file uploads that exceed this threshold.
- If not set or left empty, Palmr. automatically calculates optimal chunk sizes based on file size:
  - Files ≤ 100MB: uploaded without chunking
  - Files > 100MB and ≤ 1GB: 75MB chunks
  - Files > 1GB: 150MB chunks

**When to configure:**

- **Default (not set):** Recommended for most use cases. Palmr. will intelligently determine the best chunk size.
- **Custom value:** Set this if you have specific network conditions or want to optimize for your infrastructure (e.g., slower connections may benefit from smaller chunks like 50MB, while fast networks can handle larger chunks like 200MB, or the upload size per payload may be limited by a proxy like Cloudflare)

#### Install dependencies

Install all the frontend dependencies:

```bash
pnpm install
```

#### Build and run the frontend

Build the production version of the frontend:

```bash
pnpm run build
```

Once that's done, serve it up:

```bash
pnpm serve
```

Now, open your browser and head to:

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

You should see the full Palmr. application ready to go!

---

## Quick notes

This guide sets up Palmr. using the local file system for storage. Want to use an S3-compatible object storage instead? You can configure that in the `.env` file. Check the Palmr. documentation for details on setting up S3 storage just update the environment variables, then build and run as shown here.

### Custom Installation Paths and Symlinks

If you're using a custom installation setup with symlinks (for example, `/opt/palmr_data/uploads -> /mnt/data/uploads`), you might encounter issues with disk space detection. Palmr. includes a `CUSTOM_PATH` environment variable to handle these scenarios:

```bash
# In your .env file (apps/server/.env)
CUSTOM_PATH=/opt/palmr_data
```

This tells Palmr. to check your custom path first when determining available disk space, ensuring proper detection even when using symlinks or non-standard directory structures.

---

## Command cheat sheet

Here's a quick reference for all the commands we've covered perfect for copy-pasting once you're familiar with the steps:

```bash
# --- Backend (Fastify API) ---
cd apps/server
pnpm install
pnpm dlx prisma generate
pnpm dlx prisma migrate deploy
pnpm db:seed
pnpm run build
pnpm start

# --- Frontend (Next.js) ---
cd apps/web
pnpm install
pnpm run build
pnpm serve
```

> **Tip**: Keep this handy in your clipboard for your first setup run.

---

## What's next?

Palmr. is now up and running locally . Here are some suggested next steps:

- **Manage Users**: Dive into the [Users Management](/docs/3.2-beta/manage-users) guide.
- **Switch to Object Storage**: Update `.env` variables to use an S3-compatible bucket (see Quick Notes above).
- **Secure Your Instance**: Put Palmr. behind a reverse proxy like **Nginx** or **Caddy** and enable HTTPS.
- **Learn the Internals**: Explore how everything connects in the [Architecture](/docs/3.2-beta/architecture) overview.

Jump into whichever area fits your needs our docs are designed for exploration in any order.

## Wrapping up

Congrats! You've successfully set up a production-ready instance of Palmr. through this detailed manual process. From cloning the repo to deploying the app, you've tackled every step like a pro.

## Helpful resources

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