mirror of
https://github.com/kyantech/Palmr.git
synced 2025-10-23 06:11:58 +00:00
8f30883404
- Updated versioning across multiple components and documentation to v3.0-beta. - Introduced new Docker Compose configurations for S3-compatible storage and MinIO support. - Enhanced the documentation with new guides for API usage, architecture, and user management. - Improved localization and user experience in the frontend with updated UI components and styles. - Removed outdated Docker configurations and files to streamline the setup process. - Added new utilities for key generation and improved error handling in various components. - Updated license to reflect the new Kyantech-Permissive License.
252 lines
6.8 KiB
Plaintext
252 lines
6.8 KiB
Plaintext
---
|
|
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.0-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.
|
|
|
|
#### 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.
|
|
|
|
---
|
|
|
|
## 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.0-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.0-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/)
|