Palmr.

Manual Installation

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) 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:

  • Node.js (Powers our JavaScript/TypeScript apps)
  • pnpm (Our go-to package manager)
  • Git (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:

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:

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:

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:

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:

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:

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:

pnpm db:seed

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

Build and run the backend

Finally, build the backend app:

pnpm run build

Once the build is complete, start the service:

pnpm start

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

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.

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

cd ../web

Or, from the repo root, use:

cd apps/web

Configure environment variables

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

cp .env.example .env

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

Install dependencies

Install all the frontend dependencies:

pnpm install

Build and run the frontend

Build the production version of the frontend:

pnpm run build

Once that's done, serve it up:

pnpm serve

Now, open your browser and head to:

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.

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:

# --- 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 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 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

On this page