paulmataruso/Palmr
1
0
Fork 0
mirror of https://github.com/kyantech/Palmr.git synced 2025-10-22 22:02:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: update documentation and configuration for v3.1-beta release

Browse Source 
- Enhanced package.json with new linting, formatting, and type-checking scripts to improve code quality.
- Updated pnpm-lock.yaml to reflect dependency changes and ensure compatibility with the latest versions.
- Removed deprecated documentation files from the 1.1.7-beta version and added new content for the 3.1-beta release, including OIDC authentication guides and S3 provider configurations.
- Improved layout and styling in the documentation for better user experience.
- Updated the default version in constants to v3.1-beta, ensuring accurate routing in the application.
This commit is contained in:
Daniel Luiz Alves
2025-07-02 12:01:45 -03:00
parent 8db3304b56
commit 2c6699b604
61 changed files with 2120 additions and 2501 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
apps/docs/content/docs/1.1.7-beta/api.md
View File

@@ -1,50 +0,0 @@
---
title: API Endpoints
---
Palmr. provides a **highly documented and typed API** that can be accessed at:
- **In a production environment:** `{your_server_domain}/docs`
- **In a local environment:** [http://localhost:3333/docs](http://localhost:3333/docs)
The API documentation is powered by **Scalar** ([https://scalar.com](https://scalar.com)), which offers a fully interactive interface for testing all the available requests within Palmr. Below is an example screenshot of the API documentation interface:
![Palmr API Documentation](/assets/v1/api-docs/scalar.png)
---
### Accessing the API Documentation
We do **not provide an online version** of the API documentation because it may change depending on the specific version of Palmr. you are using. Therefore, we recommend checking the documentation only after starting your API service. The API service corresponds to the **server** within the official Palmr. GitHub repository.
---
### Scalar-Based Documentation
We recommend using **Scalar** for querying and testing the API because the system was designed with Scalar in mind. Scalar offers an intuitive and interactive environment for exploring endpoints, sending requests, and viewing responses directly within the interface.
---
### Swagger-Based Documentation
If you prefer not to use Scalar or are more comfortable with an alternative tool, a **Swagger-based version** of the documentation is also available.
![Palmr API Documentation](/assets/v1/api-docs/swagger.png)
You can access it at:
- **In a production environment:** `{your_server_domain}/swagger`
- **In a local environment:** [http://localhost:3333/swagger](http://localhost:3333/swagger)
Both the Scalar and Swagger versions contain the same endpoints and are documented at a level sufficient for testing and integrating with other systems.
---
Both options ensure that you have all the necessary tools and information to integrate Palmr. with your systems or third-party services effectively.
### Useful Links
Here are some useful links related to Palmr.'s API and its components:
- [Scalar Official Website](https://scalar.com)
- [Swagger Official Website](https://swagger.io)

54
apps/docs/content/docs/1.1.7-beta/architecture.md
View File

@@ -1,54 +0,0 @@
---
title: Architecture of Palmr.
---
##### Overview of the core architecture components of Palmr.
Understanding the architecture of Palmr. is crucial for both deploying and scaling the application. Below is a diagram illustrating the main components:
![Palmr Banner](/assets/v1/general/architecture.png)
## **Technologies Used**
Each component in the Palmr. architecture plays a vital role in ensuring reliability, performance, and scalability:
### **PostgreSQL**
Palmr. uses **PostgreSQL** as the primary database solution. It provides reliable and secure data storage, ensuring consistency and high performance for all database operations. PostgreSQL's powerful indexing, query optimization, and support for complex data types make it an ideal choice for handling large amounts of data.
### **React + TypeScript + Vite**
The frontend of Palmr. is built using **React** and **TypeScript**, bundled with **Vite** for fast development and optimized builds.
- **React** enables the creation of a dynamic and responsive user interface with a component-based architecture.
- **TypeScript** adds static typing, enhancing code quality and reducing runtime errors.
- **Vite** provides a fast and efficient development environment with hot module replacement (HMR) and optimized production builds.
### **MinIO**
Palmr. uses **MinIO** for object storage. MinIO is a high-performance, S3-compatible object storage solution designed for large-scale data infrastructure.
- Supports high-throughput file storage and retrieval.
- Ensures data integrity and redundancy.
- Compatible with AWS S3 APIs, making integration seamless.
### **Fastify**
The backend of Palmr. is powered by **Fastify**, a high-performance, low-overhead web framework for Node.js.
- Provides fast request handling with a lightweight core.
- Built-in schema-based validation for secure and reliable API handling.
- Supports plugin-based architecture for easy extensibility.
### **How It Works**
1. **Frontend** — React + TypeScript + Vite handle the user interface and user interactions.
2. **Backend** — Fastify processes requests and communicates with the database and storage layers.
3. **Database** — PostgreSQL stores metadata and transactional data.
4. **Object Storage** — MinIO stores the actual files and ensures scalable, high-performance storage.
---
### **Useful Links**
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
- [React Documentation](https://react.dev/)
- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
- [Vite Guide](https://vitejs.dev/guide/)
- [MinIO Documentation](https://min.io/docs/minio/container/index.html)
- [Fastify Documentation](https://fastify.dev/docs/latest/)
---

48
apps/docs/content/docs/1.1.7-beta/available-languages.md
View File

@@ -1,48 +0,0 @@
---
title: Available languages
---
The project uses i18next for internationalization (i18n) support. The language detection is handled automatically through i18next-browser-languagedetector .
### Available Languages in Palmr.
----
##### 1. 🇺🇸 English (en-US)
##### 2. 🇧🇷 Portuguese (pt-BR)
##### 3. 🇫🇷 French (fr-FR)
##### 4. 🇪🇸 Spanish (es-ES)
##### 5. 🇩🇪 German (de-DE)
##### 6. 🇷🇺 Russian (ru-RU)
##### 7. 🇮🇳 Hindi (hi-IN)
##### 8. 🇸🇦 Arabic (ar-SA)
##### 9. 🇯🇵 Japanese (ja-JP)
##### 10. 🇰🇷 Korean (ko-KR)
##### 11. 🇹🇷 Turkish (tr-TR)
##### 12. 🇨🇳 Chinese (zh-CN)
</br>
### Language Selection
##### The language can be changed in two ways:
#### 1. Automatic Detection
- The application automatically detects the user's browser language
- Uses the browser's language settings as the initial language
#### 2. Manual Selection
![Palmr Profile Menu](/assets/v1/main/language/language-selector.png)
- Users can manually switch languages through the language selector in the UI
- Language preference is saved in the browser's localStorage
### Default Language
##### English (en-US) is set as the fallback language.
</br>
### Language Detection
The application automatically detects the user's browser language and sets it as the initial language. Users can manually change the language using the language switcher in the interface (globe icon in the navigation bar).
### RTL Support
The application includes special handling for right-to-left (RTL) languages, specifically for Arabic (ar-SA).

67
apps/docs/content/docs/1.1.7-beta/configuring-smtp.md
View File

@@ -1,67 +0,0 @@
---
title: Configuring SMTP
---
For Palmr to function with all its best features, we need to configure our email server. To make this easier, there is a built-in configuration panel inside **Settings** in Palmr. However, only users with an **ADMIN** profile can access and configure these settings.
## Why Configure SMTP?
The main functionalities that depend on SMTP configuration are:
- **Password Reset** – Users who forget their password and cannot access the **Settings** panel need this feature.
- **Email Notifications** – Recipients will receive emails when new shares are sent to them.
Now, let's go through the step-by-step process to configure the **SMTP Server**.
---
## Accessing SMTP Settings
To access **Settings**, an **ADMIN** user must click on the profile picture in the **header** and select **Settings** from the dropdown menu.
![Dropdown Menu](/assets/v1/main/smtp/dropdown-menu.png)
Once inside the **Settings** panel, click on the **Email** card to expand the SMTP configuration options.
![Closed Settings Card](/assets/v1/main/smtp/closed-card.png)
After expanding the card, the following SMTP configuration fields will appear:
![Opened Settings Card](/assets/v1/main/smtp/opened-card.png)
---
## Configuring SMTP Server
The first step is to **enable SMTP** by selecting "Yes" in the **SMTP Enabled** field.
![SMTP Enabled](/assets/v1/main/smtp/smtp-enabled.png)
Once SMTP is enabled, you can configure the other necessary fields:
- **Sender Name** – This will appear as the sender’s name in emails. (Example: "Palmr")
- **Sender Email** – The email address from which notifications will be sent. (Example: "noreply@palmr.app")
- **SMTP Server** – The SMTP server address. You can use any email service provider. For Gmail, use `smtp.gmail.com` (this is the recommended option and set as default).
- **SMTP Port** – The server port. For Gmail, the standard port is **587**.
- **SMTP Username** – The username for the SMTP server. For Gmail, enter your email address.
- **SMTP Password** – The SMTP password. (Generate an App Password for Gmail)
> **Important:** If using **Gmail**, you need to generate an **App Password** instead of using your standard email password.
> For other email services, consult the official documentation of the service provider you are using. We recommend using Gmail for simplicity and limits the number of emails sent.
---
## Generating a Gmail App Password
To generate an App Password for Gmail:
1. Go to [Google My Account](https://myaccount.google.com/).
2. Select **Security**.
3. Scroll down to **App Passwords**.
4. Generate a new password specifically for Palmr.
For a complete guide, refer to: **[How to set up SMTP credentials with Gmail](https://medium.com/rails-to-rescue/how-to-set-up-smtp-credentials-with-gmail-for-your-app-send-email-cf236d11087d)**.
---
## Finalizing SMTP Configuration
After entering the correct information, save the settings. Palmr is now ready to send emails for password resets and share notifications!

161
apps/docs/content/docs/1.1.7-beta/contribute.md
View File

@@ -1,161 +0,0 @@
---
title: How to Contribute
---
Thank you for your interest in contributing to the **Palmr.** project! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. This guide will walk you through the process of contributing to Palmr.
---
### Step 1: Log in to GitHub
Before you can contribute, you need to be logged into your GitHub account. If you don't have an account yet, you can sign up for free at **[GitHub](https://github.com/)**.
---
### Step 2: Go to the Palmr Repository
Once you're logged in, go to the Palmr repository by clicking on this link: **[https://github.com/kyantech/Palmr](https://github.com/kyantech/Palmr)**.
Alternatively, you can search for "Palmr" in the GitHub search bar and click on the repository owned by **kyantech**.
---
### Step 3: Fork the Repository
To contribute to the project, you’ll need to create your own copy of the repository. This is called a **fork**. Here’s how to do it:
1. Click the **Fork** button at the top right of the repository page.
2. This will create a copy of the repository under your GitHub account.
---
### Step 4: Clone Your Forked Repository
Next, you’ll need to clone your forked repository to your local machine. Here’s how:
1. On your forked repository page, click the **Code** button.
2. Copy the repository URL (HTTPS or SSH).
3. Open your terminal or command prompt and run the following command to clone the repository:
```bash
git clone <repository-url>
```
4. Navigate into the cloned directory:
```bash
cd Palmr
```
---
### Step 5: Set Up the `next` Branch as the Base
Before making changes, ensure your local repository is set up to track the `next` branch from the original Palmr repository. Here’s how:
1. Add the original Palmr repository as a remote:
```bash
git remote add upstream https://github.com/kyantech/Palmr.git
```
2. Fetch the latest changes from the `next` branch:
```bash
git fetch upstream next
```
3. Create a new branch for your contribution based on `upstream/next`:
```bash
git checkout -b your-branch-name upstream/next
```
---
### Step 6: Make Your Changes
Now you’re ready to make your contributions! This could include:
- Fixing a bug
- Adding a new feature
- Improving documentation
- Writing tests
Make your changes in your local repository using your preferred code editor.
---
### Step 7: Commit Your Changes Using Conventional Commits
Once you’ve made your changes, commit them to your branch using **Conventional Commits**. Conventional Commits help maintain a clean and consistent commit history. Here’s how to format your commit messages:
#### Commit Message Format:
`<type>(<scope>): <description>`
#### Examples:
- `feat: add user authentication`
- `fix(api): resolve null pointer exception`
- `docs: update README file`
- `chore: update dependencies`
#### Steps to Commit:
1. Stage your changes:
```bash
git add .
```
2. Commit your changes with a properly formatted message:
```bash
git commit -m "feat: add new feature for user profiles"
```
---
### Step 8: Push Your Changes to GitHub
After committing your changes, push them to your forked repository on GitHub:
```bash
git push origin your-branch-name
```
---
### Step 9: Open a Pull Request to the `next` Branch
Now that your changes are on GitHub, you can open a **Pull Request (PR)** to propose your changes to the `next` branch of the Palmr repository. Here’s how:
1. Go to your forked repository on GitHub.
2. Click the **Pull Request** button.
3. On the PR creation page:
- Set the **base repository** to `kyantech/Palmr`.
- Set the **base branch** to `next`.
- Set the **head repository** to your forked repository.
- Set the **compare branch** to your branch (`your-branch-name`).
4. Fill out the PR form with a clear title and description of your changes.
5. Click **Create Pull Request**.
---
### Step 10: Wait for Review
Once your PR is submitted, the maintainers will review your changes. They may provide feedback or request additional changes. Be sure to respond to their comments and make any necessary updates.
---
### Tips for Contributing
To ensure your contribution is accepted, follow these tips:
- **Use Conventional Commits**: Write clear and consistent commit messages using the Conventional Commits format.
- **Keep Your PRs Small**: Focus on one issue or feature per PR to make it easier to review.
- **Be Patient**: Maintainers are often volunteers and may take some time to review your PR.
---
### Why Contributing is Important
Contributing to open-source projects like Palmr has many benefits:
1. **Improves the Project**: Your contributions help make the project better for everyone.
2. **Builds Your Skills**: You’ll gain experience working with Git, GitHub, and collaborative coding.
3. **Supports the Community**: Open-source thrives on community contributions. Your work helps sustain the project.
---
### Conclusion
That's it! You've successfully contributed to the **🌴 Palmr.** project on GitHub. Thank you for your time and effort in making Palmr better for everyone. We appreciate your contribution!

128
apps/docs/content/docs/1.1.7-beta/generate-share.md
View File

@@ -1,128 +0,0 @@
---
title: Creating a share
---
To create a share in Palmr, the process is very intuitive and self-explanatory. There are multiple ways to create a share, but the most straightforward method is through the **Home Page**, specifically in the **Recent Shares** section.
## Home Page
On the home page, there is a **"Recent Shares"** section. When no shares have been created yet, this section will appear as follows:
![Recent Shares Section](/assets/v1/main/shares/share-section.png)
Since no shares exist yet, you will see a **"Create Share"** button prominently displayed.
![Create Share Button](/assets/v1/main/shares/create-first-share.png)
> **Note:** You don’t need to upload files to create a share! Yes, it’s entirely possible to create a share without adding any files. While this might not make sense in every scenario, some users and use cases find this feature highly valuable.
As mentioned above, shares in Palmr are created first with their settings, and then files can be added later. You can also edit a share at any time.
To create a share, simply click the **"Create Share"** button in the center of the **Recent Shares** section. Doing so will open the following **Create Share** modal:
![Create Share Modal](/assets/v1/main/shares/create-share-modal.png)
Fill in the required information in the modal. The fields **Expiration Date**, **Max Views**, and **Password** are optional but significantly impact how the share functions for recipients:
- **Password:** If set, the recipient must enter the correct password to access the share.
- **Max Views:** If the limit is reached, the share will no longer be accessible unless the creator increases or removes the limit.
- **Expiration Date:** After the expiration date, the share will automatically be disabled unless extended by the creator.
Even the **name** field is optional, but we recommend setting a name for better organization.
Once a share is created, the **Recent Shares** section updates to display a table with the following fields:
- **Name**
- **Created At**
- **Expires At**
- **Status**
- **Security**
- **Files**
- **Recipients**
- **Actions**
![Shares Table](/assets/v1/main/shares/shares-table.png)
To create additional shares, a **"New Share"** button appears in the upper right corner of the **Recent Shares** section.
![New Share Button](/assets/v1/main/shares/new-share-btn.png)
Clicking this button will reopen the **Create Share** modal.
The **Recent Shares** section displays only the **last 5 shares**. To view all created shares, click the **"View All"** button.
![Shares Filled](/assets/v1/main/shares/recent-shares-filled.png)
![View All Button](/assets/v1/main/shares/view-all-button.png)
Clicking this redirects you to the **Shares Management** page.
![Shares Management Page](/assets/v1/main/shares/my-shares-page.png)
Another way to access the **Shares Management** page is by clicking the **"My Shares"** card on the home page.
![My Shares Card](/assets/v1/main/shares/my-shares-card.png)
---
## Shares Management Page
The **Shares Management** page is similar to the **Uploads Management** page, but here, you can **add, remove, edit, and view all created shares** without the limitation of only displaying the last 5 shares.
##### Each share has an **Actions** column with the following options:
![Actions Column](/assets/v1/main/shares/actions-column.png)
## Edit Share
Clicking the **Edit** button allows you to modify the share details.
![Edit Share Modal](/assets/v1/main/shares/edit-share-modal.png)
## Manage Files
Clicking the **Manage Files** button lets you add or remove files from the share.
![Manage Files Modal](/assets/v1/main/shares/manage-files-modal.png)
## Manage Recipients
Clicking the **Manage Recipients** button lets you add or remove recipients for the share.
> **Note:** Email notifications will only be sent if SMTP settings are properly configured in the system.
![Manage Recipients Modal](/assets/v1/main/shares/manage-recipients-modal.png)
## View Share Details
Clicking **View Details** lets you see all details of a share.
![View Details Modal](/assets/v1/main/shares/share-details-modal.png)
## Generate Share Link
Clicking the **Generate Link** button creates a shareable link, which can be customized.
![Generate Link Modal](/assets/v1/main/shares/generate-share-link-modal.png)
Once generated, you can view and copy the link.
![Copy Link Modal](/assets/v1/main/shares/copy-link-modal.png)
The generated link can be edited or copied from a dropdown menu.
![Edit or Copy Link Dropdown](/assets/v1/main/shares/dropdown-with-copy.png)
When the generated link is accessed, the recipient can **view and download** the shared files.
![Shared Page Preview](/assets/v1/main/shares/share-screen.png)
## Delete Share
Clicking the **Delete** button allows you to permanently remove a share.
![Delete Share Modal](/assets/v1/main/shares/delete-share-modal.png)
---
## Summary
Palmr’s share creation process is intuitive and flexible. You can create a share without files, edit share settings, manage recipients, and generate shareable links. The **Shares Management** page provides a full overview of all shares, ensuring you have complete control over your file-sharing process.

77
apps/docs/content/docs/1.1.7-beta/gh-sponsor.md
View File

@@ -1,77 +0,0 @@
---
title: Github Sponsors
---
Sponsoring a project on GitHub is a powerful way to support its development and ensure its long-term sustainability. This tutorial will guide you through the process of sponsoring the **Palmr.** project on GitHub using GitHub Sponsors.
---
### Step 1: Log in to GitHub
Before you can star a project, you need to be logged into your GitHub account. If you don't have an account yet, you can sign up for free at [GitHub](https://github.com/).
---
### Step 2: Go to the Palmr. Repository
Once you're logged in, go to the Palmr. repository by clicking on this link: [https://github.com/kyantech/Palmr](https://github.com/kyantech/Palmr).
Alternatively, you can search for "Palmr" in the GitHub search bar and click on the repository owned by **Kyantech**.
---
### Step 3: Click on the "Sponsor" Button
On the Palmr repository page, you'll see a "Sponsor" button at the top right corner of the page. Click this button to proceed.
![Palmr Profile Menu](/assets/v1/sponsor/sponsor-btn.png)
---
### Step 4: Choose a Custom Sponsorship Amount
GitHub Sponsors allows you to sponsor the project with a **custom amount starting at $1**. Here's how to do it:
1. On the sponsorship page, look for the option to **enter a custom amount**.
2. Type in the amount you'd like to sponsor (e.g., $1, $5, $10, or any amount you choose).
3. Select the billing frequency (monthly or one-time).
![Palmr Profile Menu](/assets/v1/sponsor/sponsor-page.png)
---
### Step 5: Complete the Sponsorship
After entering your custom amount and selecting the billing frequency, you'll be prompted to enter your payment details. Follow the instructions to complete the sponsorship process. Once done, you'll officially be a sponsor of the Palmr project!
---
### Why Sponsoring is Important for Project Development
Sponsoring a project goes beyond starring—it provides direct financial support to the developers, enabling them to focus on improving and maintaining the project. Here's why sponsoring is so important:
#### 1. **Supports Sustainability**
- Sponsoring helps ensure the long-term sustainability of the project by providing developers with the resources they need to continue their work.
#### 2. **Encourages Innovation**
- Financial support allows developers to experiment, innovate, and add new features to the project.
#### 3. **Shows Deep Appreciation**
- Sponsoring is a tangible way to show your appreciation for the hard work and effort that goes into maintaining and developing a project.
#### 4. **Gives You Recognition**
- Many projects offer recognition for sponsors, such as listing your name or company on the project's README or website.
#### 5. **Helps Open Source Thrive**
- Open-source projects like Palmr rely on community support. By sponsoring, you're contributing to the growth and success of the open-source ecosystem.
---
### A Meaningful Way to Give Back
Sponsoring a project is a meaningful way to give back to the developers who create the tools and software you rely on. Even a small contribution of **$1** can make a big difference. Your support ensures that Palmr continues to grow and improve. Thank you for considering sponsoring! 💖
---
### Conclusion
That's it! You've successfully sponsored the **Palmr** project on GitHub. Your contribution, no matter the amount, will help ensure the project continues to grow and improve. Thank you for your support!

72
apps/docs/content/docs/1.1.7-beta/gh-star.md
View File

@@ -1,72 +0,0 @@
---
title: Star this project on Github
---
Starring a project on GitHub is a great way to show appreciation for a repository and to bookmark it for easy access later. This tutorial will guide you through the process of starring the **Palmr** project on GitHub.
---
### Step 1: Log in to GitHub
Before you can star a project, you need to be logged into your GitHub account. If you don't have an account yet, you can sign up for free at [GitHub](https://github.com/).
---
### Step 2: Go to the Palmr. Repository
Once you're logged in, go to the Palmr. repository by clicking on this link: [https://github.com/kyantech/Palmr](https://github.com/kyantech/Palmr).
Alternatively, you can search for "Palmr" in the GitHub search bar and click on the repository owned by **Kyantech**.
---
### Step 3: Star the Repository
On the Palmr. repository page, you'll see a "Star" button at the top right corner of the page. Click this button to star the repository.
![Palmr Profile Menu](/assets/v1/sponsor/star-btn.png)
---
### Step 4: Confirm the Star
After clicking the "Star" button, the button will change to "Unstar," indicating that the repository has been successfully starred. You can always unstar the repository by clicking the "Unstar" button.
![Palmr Profile Menu](/assets/v1/sponsor/starred-button.png)
---
### Why Starring is Important for Project Development
Starring a repository on GitHub is more than just a bookmarking tool—it’s a way to support the project and its developers. Here’s why starring is so important:
#### 1. **Shows Appreciation**
- Starring a repository is a simple way to show your appreciation for the hard work and effort that goes into maintaining and developing a project. It’s like giving a thumbs-up to the developers!
#### 2. **Increases Visibility**
- The more stars a repository has, the more visible it becomes on GitHub. This can attract more contributors, users, and even potential sponsors, which helps the project grow.
#### 3. **Encourages Developers**
- Seeing stars on a repository motivates developers to continue improving the project. It’s a sign that people find the project useful and valuable.
#### 4. **Helps with Discovery**
- GitHub’s trending and recommendation algorithms often prioritize repositories with more stars. By starring Palmr, you’re helping others discover it more easily.
#### 5. **Tracks Your Interests**
- Starring a repository adds it to your "Starred" list, making it easy for you to find and revisit the project later. It’s a great way to keep track of projects you love or want to follow.
#### 6. **Supports Open Source**
- Open-source projects like Palmr thrive on community support. By starring the repository, you’re contributing to the open-source ecosystem and helping ensure the project’s longevity.
---
### A Small Action with a Big Impact
Starring a repository takes just a second, but it can have a huge impact on the project’s growth and development. Your support means a lot to the developers and the community behind Palmr. So, if you find the project useful, don’t forget to hit that **Star** button! ⭐
---
### Conclusion
That's it! You've successfully starred the **Palmr.** project on GitHub. Starring repositories is a simple yet powerful way to keep track of projects you find interesting or useful. Thank you for supporting Palmr!

80
apps/docs/content/docs/1.1.7-beta/github-architecture.md
View File

@@ -1,80 +0,0 @@
---
title: Github Architecture
---
## Project Structure
```plaintext
├── apps/
│ ├── web/ # Frontend application
│ ├── server/ # Backend API service
│ └── docs/ # Documentation site
└── composes/ # Docker compose configurations
configurations
```
## Core Components
### 1. Frontend Application (apps/web)
##### Technology Stack:
- React 18
- TypeScript
- Vite
- HeroUI Components
- TailwindCSS
- i18next for internationalization
##### The frontend follows a feature-based architecture with:
- Components-based structure
- Custom hooks for business logic
- Route protection system
- File management system
- Modal system for file operations
### 2. Backend Service (apps/server)
##### Technology Stack:
- Fastify
- PostgreSQL
- MinIO for object storage
- Prisma as ORM
##### Key features include:
- User authentication/authorization
- File management
- Storage management
- Share system
### 3. Documentation (apps/docs)
- Built with Astro and Starlight
- Provides comprehensive documentation for the project
### 4. Infrastructure
- Docker-based deployment
- Containerized services
- Environment-specific configurations through docker-compose
## Key Features
##### 1. File Management
- Upload/Download capabilities
- File preview system
- Share management
- Storage usage monitoring
##### 2. User System
- Authentication
- User management
- Profile management
##### 3. Storage System
- MinIO integration for object storage
- Disk space monitoring
- Upload size validation
##### 4. Internationalization
- Multi-language support
- Translation management

42
apps/docs/content/docs/1.1.7-beta/index.md
View File

@@ -1,42 +0,0 @@
---
title: Welcome to Palmr.
---
![Palmr Banner](/assets/v1/general/banner.png)
## 🌴 What is **Palmr.** ?
___
**Palmr.** is a powerful and **flexible open-source alternative** to popular file transfer services like **WeTransfer**, **SendGB**, **Send Anywhere** and **Files.fm**. The key advantage of Palmr. is that you can **host it on your own infrastructure**, such as a **dedicated server** or **VPS**, giving you full control over your files and data security — without relying on third-party services or worrying about artificial limits or high fees.
## **Why Choose Palmr.?**
___
### **1. No Artificial Limits**
Unlike traditional services, Palmr. does not impose file size or quantity limits. The only limit is the **available storage** on your server or VPS. If you have the storage capacity, you can send files without restrictions, no premium plans, no ads, and no hidden fees.
### **2. Open Source and Free**
Palmr. is completely **open source** and free to use. You can:
- Deploy it on any infrastructure (VPS, dedicated server, Docker, etc.).
- Review and audit the code to ensure security and integrity.
- Contribute improvements or custom features.
- Adapt it for different use cases as needed.
### **3. Security and Privacy Under Your Control**
By hosting Palmr. on your own infrastructure, you retain **full control over your data**. Your files are not stored or processed by third parties, ensuring **privacy** and **confidentiality** of transferred information.
### **4. Highly Customizable**
Palmr. is fully customizable, allowing you to align it with your brand identity and user experience:
- Add your own **logo**.
- Set a **custom app name**.
- Configure an **SMTP server** for email notifications.
- Customize some text to create a unique experience for users.
### **5. Complete User and Admin Management**
Palmr. offers a robust user and admin management system:
- Create and manage multiple **administrators** .
- Add unlimited **users**.
- Control who can view, upload, and manage files.
- Easily monitor usage.
### **6. Fast, Lightweight, and Scalable**
Palmr. is designed to be lightweight and scalable, ensuring high performance even with large files or high user traffic. Its efficient architecture allows you to scale easily as your needs grow.

135
apps/docs/content/docs/1.1.7-beta/installation.mdx
View File

@@ -1,135 +0,0 @@
---
title: Installation (Docker Compose)
---
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
### Quick Start with Default Docker Compose
There is a default `docker-compose.yml` file in the project root that can be used for quick execution. While this provides a convenient way to get started, it's important to note that using the default passwords is **not secure**, especially if the application is exposed to public networks. Malicious users could potentially exploit known default credentials to attack your deployment.
This base Docker Compose configuration works perfectly for localhost development but may require modifications when deployed to a VPS or production environment for optimal performance and security. Please consult the complete documentation for proper production deployment configurations.
For a quick start using the default configuration, simply run:
```bash
docker compose up -d
```
This command will start the project using the default configuration.
> ⚠️ **Important:** We strongly recommend testing your configuration locally first, especially if you've made any modifications to the Docker Compose files. Only after confirming everything works as expected locally should you proceed with deployment to a VPS or server environment.
### Startup Script for Docker Compose
To simplify the execution of the project and enable it to run on any machine, a **startup script** for Docker Compose was created. This script automates the generation of secure credentials and facilitates local setup. While this method provides better security than using default passwords, for maximum security, we strongly recommend moving all sensitive credentials to environment variables instead.
To execute the project using this approach, you need to have **Docker** and **Docker Compose** installed on your machine. While this is the simplest way to execute the project, it is **not recommended for production environments**.
---
### Ways to Execute the Startup Script
First of all, download the relase v1.1.7-beta:
[Release version - 1.1.7-beta](https://github.com/kyantech/Palmr/releases/tag/v1.1.7-beta)
There are two ways to execute the script:
<Tabs items={['Using a Makefile', 'Running the Script Directly']}>
<Tab >
To use this method, you need to have the `make` command installed on your machine.
To generate the new `docker-compose.yml` file using a Makefile, run the following command from the project root:
```bash
make gen-compose
```
This command will subcribe the `docker-compose.yml` file in the root of the project.
- The script's primary function is to generate secure passwords for **MinIO** (object storage) and **Postgres** (database).
- The generated `docker-compose.yml` file serves as a base and can be modified at any time.
- It is configured to run locally via `localhost` and is **not intended for production** or VPS environments.
After the file is generated, you can modify or adapt it for deployment in other environments.
</Tab>
<Tab >
To generate the `docker-compose.yml` file by running the script directly, use the following commands:
```bash
chmod +x ./scripts/generate-docker-compose.sh
./scripts/generate-docker-compose.sh
```
This will have the same effect as running `make gen-compose`.
</Tab>
</Tabs>
---
### Running the Project
After generating the new `docker-compose.yml` file, you can start the project by running the following command from the project root:
```bash
docker compose up -d
```
To access Palmr. in a local environment, open your browser and visit:
[http://localhost:4173](http://localhost:4173)
---
### Deployment in Production
For production environments with high scalability and availability requirements, we recommend using **Kubernetes**, **Docker Swarm**, or a similar container orchestrator.
For homelab, personal projects, or environments where high availability and scalability are not critical, Docker Compose can be used without issues. The `docker-compose.yml` file pulls the latest Palmr. images from Docker and makes them available on specific ports, as shown below:
- **Frontend:** [http://localhost:4173](http://localhost:4173)
- **Backend:** [http://localhost:3333](http://localhost:3333)
- **MinIO API:** [http://localhost:9000](http://localhost:9000)
- **MinIO Console:** [http://localhost:9001](http://localhost:9001)
- **Postgres Database:** [http://localhost:5423](http://localhost:5423)
---
### Port Configuration Recommendations
In this version of `docker-compose.yml`, none of the ports for the frontend and backend should be modified. Consequently, none of the URLs should be changed because the frontend image contains a pre-built version configured to work on port **4173**.
> ⚠️ Due to technical limitations related to **ReactJS**, environment variables executed at runtime cannot be changed. Therefore, to ensure that the system functions correctly as designed, keep the `docker-compose.yml` file unchanged.
---
### Running in Development Mode
If you want to modify the ports in a local environment and run the project using Docker with Docker Compose, we recommend using the `docker-compose-dev.yaml` file. This file builds the project based on the files in the cloned repository.
When using `docker-compose-dev.yaml`, make sure to configure all port and URL settings correctly. Incorrect configuration will prevent Palmr. from functioning as expected.
---
### Docker Compose in Production Environments
We **do not recommend** using `docker-compose.yml` in production or VPS environments. Docker Compose is designed for development and testing purposes only, not for handling production workloads.
---
### Recommended Deployment for Production
For production environments, we recommend using **Kubernetes**. However, the repository does not include a ready-to-use Kubernetes configuration, so you will need to configure it manually.
Alternatively, you can set up the application using separate services as follows:
- **Frontend:** Host on **Vercel** or **AWS Amplify**.
- **Backend:** Host on **Render.com** or similar services.
- **MinIO:** Deploy separately on a server using Docker.
- **Database:** Host on a managed service like **Neon.tech**.
---
### Environment Variables
The Palmr. code is completely open-source, allowing you to adjust the deployment to meet your needs. Ensure that the environment variables are correctly configured to avoid issues during execution.
---
### Additional Resources
- [Docker Documentation](https://docs.docker.com/)
- [Docker Compose Documentation](https://docs.docker.com/compose/)
- [Kubernetes Documentation](https://kubernetes.io/docs/)
- [MinIO Documentation](https://min.io/docs/minio/container/index.html)
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)

104
apps/docs/content/docs/1.1.7-beta/login.md
View File

@@ -1,104 +0,0 @@
---
title: First Login (Admin)
---
Once you have started all the services as described in the deployment instructions, you will be able to access the frontend at:
- **Production environment:** `{your_web_domain}`
- **Local environment:** [http://localhost:4173](http://localhost:4173)
Upon accessing the frontend, you will see a screen similar to the image below:
![Palmr Landing Page](/assets/v1/general/lp.png)
This is the **Palmr. landing page**, which provides basic information about the application. This landing page can be hidden later when you configure your app, allowing the login page to become the default home page. However, on the first execution, it is displayed by default.
---
## First Login
At the top of the landing page, you will see a button to log in to Palmr.:
> **But you may wonder:**
To simplify the process, Palmr. comes pre-configured with **seed data** upon the first initialization. This seed data includes a default **admin user** with full access to all settings and user management within the application.
After clicking the **Login** button, you will be redirected to the login screen, which looks like this:
![Palmr Login Page](/assets/v1/ui/login.png)
Use the following default credentials to log in for the first time:
| User | Password |
|------------|------------|
| `admin@example.com` | `admin123` |
If everything is set up correctly, you will be authenticated and redirected to Palmr.'s main dashboard, which looks like this:
![Palmr Dashboard](/assets/v1/ui/dashboard.png)
At this point, you are officially logged in and ready to start using all the features of Palmr.!
---
## Recommendations After First Access
Since Palmr. includes a single default admin user in the seed data, it is **highly recommended** to change the default admin credentials immediately after the first login. This is crucial for maintaining the security of your instance.
Follow these steps to update the admin credentials and secure your Palmr. instance:
### Step 1: Access the Profile Settings
1. Click the **user icon** located in the top right corner of the screen.
2. A dropdown menu will appear with several options:
![Palmr Profile Menu](/assets/v1/ui/menu.png)
3. Select **"Profile"** from the dropdown menu. This will redirect you to the profile settings page:
![Palmr Profile Page](/assets/v1/ui/profile.png)
---
### Step 2: Update the Admin Profile
On the profile settings page, you can update all the information related to the admin account.
- To update the password, enter a new secure password and confirm it.
- Update other details as needed based on your preferences.
**Tip:** For better security, use a strong password containing:
- At least 12 characters
- A mix of uppercase and lowercase letters
- Numbers and special characters
---
### Step 3: Update the Profile Picture
You can also update the profile picture for better personalization.
1. Click the **camera icon** next to the avatar.
2. Select an image from your local device.
![Palmr Profile Picture](/assets/v1/ui/profile_picture.png)
> **Recommendation:** Use a square image to ensure proper display.
---
## Troubleshooting
If you encounter any issues during the first login or profile update, please check the following:
- Ensure that all services (frontend, backend, MinIO, and database) are running correctly.
- Make sure the environment variables are properly configured.
- Confirm that the database seeds have been applied correctly.
---
## Security Best Practices
- After setting up your admin account, create separate user accounts with limited access based on roles.
- Use HTTPS to secure the connection between the client and the server.
- Regularly update the Palmr. instance to benefit from the latest security patches and improvements.
---

85
apps/docs/content/docs/1.1.7-beta/manage-users.md
View File

@@ -1,85 +0,0 @@
---
title: Manage users
---
Manage users to **Palmr** is a straightforward process. Below is a detailed step-by-step guide explaining how to create and manage users within the application.
### Step 1: Accessing User Management
To begin, you need to navigate to the **User Management** section:
1. Click on the **user icon** located in the header of the app.
2. A dropdown menu will appear. From the options available, select **"User Management"**
![Palmr Profile Menu](/assets/v1/ui/menu.png)
---
### Step 2: User Management Dashboard
After selecting **User Management**, you will be redirected to the **User Management Dashboard**.
- On your first access, the only user listed will be the **default Admin** user.
- If you need to update the Admin user details, you must follow the steps outlined in the **Profile Management** section.
- User details for the logged-in Admin cannot be modified from the **User Management Dashboard**.
![Palmr Profile Menu](/assets/v1/main/users/users-management.png)
---
### Step 3: Adding a New User
1. To add a new user, click on the **"Add User"** button located at the top right corner of the screen.
![Palmr Profile Menu](/assets/v1/main/users/add-users-btn.png)
2. A modal form will appear, allowing you to enter the new user's details:
![Palmr Profile Menu](/assets/v1/main/users/add-user-modal.png)
3. After filling in the user details, click on **"Create"** to confirm.
Alternatively, you can click **"Cancel"** to abort the user creation process.
4. Once the user is created successfully, it will appear in the user list.
![Palmr Profile Menu](/assets/v1/main/users/new-user-table.png)
---
### Step 4: Managing User Actions
In the **User List**, under the **"Actions"** column, you will find a dropdown menu for each user.
![Palmr Profile Menu](/assets/v1/main/users/add-user-actions-dropdown.png)
Available actions include:
- **Edit User** – Opens a modal form to update user information:
- Change user details including role.
- Change the user password.
![Palmr Profile Menu](/assets/v1/main/users/edit-user-modal.png)
- **Deactivate User** – Marks the user as inactive, preventing them from logging into the system.
- **Activate User** – Reactivates a deactivated user, allowing them to log in again.
- **Delete User** – Permanently removes the user from the system.
---
### Troubleshooting
#### User Creation Fails
- Ensure all mandatory fields (name, email, role) are filled out correctly.
- Check for duplicate emails.
- Verify that the system has proper connectivity to the backend.
#### User Cannot Log In
- Ensure the user is marked as **Active**.
- Verify that the correct email and password are being used.
- Reset the user password if needed.

170
apps/docs/content/docs/1.1.7-beta/manual-installation.mdx
View File

@@ -1,170 +0,0 @@
---
title: 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:
```bash
git clone https://github.com/kyantech/Palmr.git
```
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:
```bash
cd ./apps/server
```
Inside this folder, you can start by running:
```bash
docker compose up -d
```
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:
```bash
cp .env.example .env
```
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:
```bash
pnpm install
```
#### 3.3: Generate Prisma Client
After the installation is complete, run the following command:
```bash
pnpm dlx prisma generate
```
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:
```bash
pnpm dlx prisma migrate deploy
```
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:
```bash
pnpm db:seed
```
Now, our database is ready for the project to run.
#### 3.6: Build and Run the Backend
To run the backend, simply execute:
```bash
pnpm run build
```
This command builds the application for production. After the build is complete, run:
```bash
pnpm start
```
Following these steps, the backend will be functional. To test it, you can access:
```bash
http://localhost:3333/docs
```
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:
```bash
cd ../web
```
If you are in the root of the repository:
```bash
cd apps/web
```
#### 4.2: Set Up Environment Variables
Once in the web directory, first run:
```bash
cp .env.example .env
```
This populates the environment variables, just like in the backend.
#### 4.3: Install Dependencies
Next, install the dependencies:
```bash
pnpm install
```
#### 4.4: Build and Run the Frontend
Now, the process for the frontend is simpler. We can simply run the build with:
```bash
pnpm run build
```
Once the build is complete, start the service with:
```bash
pnpm preview
```
Wait for the service to start, and then you can test the entire application at:
```bash
http://localhost:4173
```
##### Conclusion
That's it! This is the step-by-step guide to manually running a production version of Palmr.
### 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/)

28
apps/docs/content/docs/1.1.7-beta/meta.json
View File

@@ -1,28 +0,0 @@
{
"title": "v1.1.7-beta",
"description": "(Deprecated)",
"root": true,
"icon": "Trash2",
"pages": [
"---Introduction---",
"index",
"architecture",
"github-architecture",
"installation",
"manual-installation",
"api",
"---How to use Palmr.---",
"login",
"manage-users",
"upload",
"generate-share",
"configuring-smtp",
"available-languages",
"---Developers---",
"contribute",
"open-an-issue",
"---Sponsor this project---",
"gh-star",
"gh-sponsor"
]
}

81
apps/docs/content/docs/1.1.7-beta/open-an-issue.md
View File

@@ -1,81 +0,0 @@
---
title: How to open an issue
---
Opening an issue on GitHub is a great way to report bugs, request features, or ask questions about a project. This tutorial will guide you through the process of opening an issue for the **Palmr.** project on GitHub.
---
### Step 1: Log in to GitHub
Before you can star a project, you need to be logged into your GitHub account. If you don't have an account yet, you can sign up for free at [GitHub](https://github.com/).
---
### Step 2: Go to the Palmr. Repository
Once you're logged in, go to the Palmr. repository by clicking on this link: [https://github.com/kyantech/Palmr](https://github.com/kyantech/Palmr).
Alternatively, you can search for "Palmr" in the GitHub search bar and click on the repository owned by **Kyantech**.
---
### Step 3: Navigate to the Issues Tab
On the Palmr repository page, click on the **Issues** tab near the top of the page. This will take you to the issues section of the repository.
![Palmr Profile Menu](/assets/v1/developers/issues-tab.png)
---
### Step 4: Click on "New Issue"
Once you're in the issues section, click the **New Issue** button to start creating a new issue.
![Palmr Profile Menu](/assets/v1/developers/new-issue-btn.png)
---
### Step 5: Fill Out the Issue Form
You’ll now see a form where you can provide details about your issue. Here’s how to fill it out:
1. **Title**: Write a clear and concise title that summarizes the issue.
2. **Description**: Provide a detailed description of the issue. Include steps to reproduce the problem (if it’s a bug), expected behavior, and actual behavior. If you’re requesting a feature, explain why it would be useful.
3. **Labels (Optional)**: Add labels to categorize your issue (e.g., `bug`, `enhancement`, `question`). This helps the maintainers organize and prioritize issues.
4. **Attachments (Optional)**: You can attach screenshots, logs, or other files to help explain the issue.
![Palmr Profile Menu](/assets/v1/developers/new-issue-form.png)
---
### Step 6: Submit the Issue
Once you’ve filled out the form, click the **Create** button. Your issue will now be visible to the project maintainers and other contributors.
---
### Tips for Writing a Good Issue
To ensure your issue is addressed quickly and effectively, follow these tips:
- **Be Clear and Specific**: Provide as much detail as possible.
- **Use a Descriptive Title**: A good title helps maintainers understand the issue at a glance.
- **Include Steps to Reproduce**: If it’s a bug, explain how to reproduce it.
- **Be Polite and Respectful**: Remember that maintainers and contributors are volunteering their time.
---
### Why Opening Issues is Important
Opening issues is a key part of contributing to open-source projects. Here’s why it matters:
1. **Improves the Project**: Your feedback helps identify bugs and suggest new features.
2. **Helps Maintainers**: Clear and detailed issues make it easier for maintainers to address problems.
3. **Encourages Collaboration**: Issues can spark discussions and attract contributors to help solve problems.
---
### Conclusion
That's it! You've successfully opened an issue for the **Palmr** project on GitHub. Your contribution helps improve the project and supports the open-source community. Thank you for taking the time to share your feedback!

94
apps/docs/content/docs/1.1.7-beta/upload.md
View File

@@ -1,94 +0,0 @@
---
title: Uploading Files
---
To upload a file in Palmr, the process is very simple. There are two main locations where you can upload files.
However, before proceeding, it’s important to highlight that the core functionality of Palmr is file sharing.
But for this to work, you need to first upload one or more files to share. Later, you can create a sharing session,
which may contain one or multiple files.
Now let's focus on the file upload process. As mentioned, it is very simple, and you can upload files from two locations:
**the Home Page** or **the My Files Page**. We will go through both examples below, but the process is exactly the same in both cases.
---
## Home Page
On the home page, there is a **"Recent Uploads"** section. On the first initialization (when no file has been uploaded yet),
it will appear like this:
![Recent Uploads Section](/assets/v1/main/upload/recent-uploads.png)
To upload a file, simply click on the **"Upload File"** button. This will open a modal where you can select the file you want
to upload from your device. Some file types, such as images, audio, and video, will have a preview available.
![Upload File Button](/assets/v1/main/upload/upload-file-button.png)
### Example with an image:
![Preview Example](/assets/v1/main/upload/preview-example.png)
After selecting the file, you can either confirm the upload by clicking the **"Upload"** button or cancel the operation by clicking the **"Cancel"** button.
![Upload and Cancel Buttons](/assets/v1/main/upload/upload-cancel-buttons.png)
Once one or more files have been uploaded, the **"Recent Uploads"** section will update and look like this:
![Recent Uploads with Files](/assets/v1/main/upload/recent-uploads-filled.png)
To upload a new file from this screen, click the **"Upload File"** button in the upper right corner of the section, and follow the same steps as before.
![New Upload Button](/assets/v1/main/upload/new-upload-button.png)
This list on the home page shows only the **last 5 uploads**. To view older files or upload more, you need to go to the **"My Files"** page.
You can access this by clicking on the **"View All"** button in the upper right corner of the section or by clicking on the **"My Files"** card on the home page.
![View All Button](/assets/v1/main/upload/view-all-button.png)
Or:
![My Files Card](/assets/v1/main/files/my-files-card.png)
---
## My Files Page
On the **"My Files"** page, the layout will look like this:
![My Files Page](/assets/v1/main/files/my-files-page.png)
Here, you have the option to **filter** your uploaded files or upload new ones by clicking the **"Upload File"** button and following the same steps explained earlier.
Notice that the tables in the **"Recent Files"** section and the **"My Files"** page are the same — the only difference is the number of results shown.
The **"Recent Files"** section shows only the last 5 uploads, while the **"My Files"** table displays all uploads.
The table fields include:
- **Name**
- **Description**
- **Size**
- **Created At**
- **Updated At**
- **Actions**
### Actions Column
In the **"Actions"** column, you will find an icon that opens the following dropdown:
![Actions Dropdown](/assets/v1/main/files/actions-dropdown.png)
Each option is self-explanatory, but let’s detail the **Edit** option:
- **Edit** – Opens a modal where you can edit the file name, description, and other details.
![Edit Modal](/assets/v1/main/files/edit-modal.png)
- You can also **delete** a file directly from the dropdown by selecting the **Delete** option.
The preview feature is only available for files like images, audio, PDFs and video. For other file types,
you can download them using the **Download** option in the dropdown.
---
## Notes and Recommendations
- For a better user experience, we recommend using optimized files for upload.
- Upload errors or issues are logged and can be reviewed through the admin panel.
- Admins can manage file access permissions.

315
apps/docs/content/docs/3.0-beta/oidc-authentication.mdx
View File

@@ -1,315 +0,0 @@
---
title: OIDC Authentication
icon: Key
---
Palmr supports OpenID Connect (OIDC) authentication, allowing users to sign in using external identity providers such as Google, Microsoft Azure AD, Keycloak, Auth0, and other OIDC-compliant services. This feature provides seamless single sign-on (SSO) capabilities and centralized user management.
OIDC authentication in Palmr is built using the industry-standard OpenID Connect protocol with PKCE (Proof Key for Code Exchange) for enhanced security. The implementation supports automatic user provisioning, role mapping, and flexible configuration options.
## Why use OIDC authentication?
OIDC authentication provides several advantages for organizations and users:
**Centralized Authentication**: Users can authenticate using their existing organizational credentials without creating separate accounts for Palmr.
**Enhanced Security**: OIDC provides robust security features including token-based authentication, PKCE flow, and standardized protocols.
**Single Sign-On**: Users can access Palmr seamlessly if they're already authenticated with their identity provider.
**User Management**: Administrators can manage user access centrally through their existing identity provider.
**Compliance**: OIDC helps meet organizational security and compliance requirements by leveraging existing identity infrastructure.
---
## Prerequisites
Before configuring OIDC authentication, ensure you have:
- **Administrative Access**: ADMIN privileges in Palmr to configure OIDC settings
- **Identity Provider**: An OIDC-compliant identity provider (Google, Azure AD, Keycloak, etc.)
- **Application Registration**: Your Palmr application registered with your identity provider
- **OIDC Credentials**: Client ID, Client Secret, and Issuer URL from your identity provider
### Supported identity providers
Palmr's OIDC implementation is compatible with any OpenID Connect 1.0 compliant provider, including:
- **Google Workspace / Google Cloud Identity**
- **Microsoft Azure Active Directory / Entra ID**
- **Keycloak**
- **Auth0**
- **Okta**
- **AWS Cognito**
- **Custom OIDC providers**
---
## Configuring OIDC settings
OIDC configuration is managed through Palmr's administrative settings panel, accessible only to users with ADMIN privileges.
### Accessing OIDC configuration
To configure OIDC authentication:
1. **Access Settings**: Click on your profile picture in the header and select **Settings**
2. **Navigate to Authentication**: Find the **Authentication** or **OIDC** configuration section
3. **Enable OIDC**: Toggle the OIDC authentication option to enable it
![OIDC Settings Panel](/assets/v3/oidc/provider-setup.png)
### Required configuration fields
Configure the following essential fields for OIDC authentication:
**OIDC Enabled**: Enable or disable OIDC authentication for your Palmr instance.
**Issuer URL**: The base URL of your OIDC identity provider. This is typically the discovery endpoint URL without the `/.well-known/openid-configuration` suffix.
- Example: `https://accounts.google.com`
- Example: `https://login.microsoftonline.com/{tenant-id}/v2.0`
**Client ID**: The unique identifier for your Palmr application as registered with your identity provider.
**Client Secret**: The secret key provided by your identity provider for your Palmr application. Store this securely and never share it.
**Redirect URI**: The callback URL where users will be redirected after authentication. This is typically auto-detected but can be manually configured if needed.
- Format: `https://your-palmr-domain.com/api/auth/oidc/callback`
**Scope**: The OpenID Connect scopes to request from the identity provider. Default is `openid profile email`.
![OIDC Configuration Fields](/assets/v3/oidc/provider setup.png)
### Advanced configuration options
**Auto-Registration**: Configure whether new users can be automatically created when they authenticate via OIDC for the first time.
**Admin Email Domains**: Specify email domains that should automatically receive admin privileges when registering via OIDC.
**User Attribute Mapping**: Configure how user attributes from the OIDC provider map to Palmr user fields.
---
## Setting up identity providers
The setup process varies depending on your chosen identity provider. Here are examples for common providers:
### Google Workspace / Google Cloud
1. **Create Project**: Go to the [Google Cloud Console](https://console.cloud.google.com/) and create a new project
2. **Enable APIs**: Enable the Google+ API and OpenID Connect API
3. **Create Credentials**: Create OAuth 2.0 credentials for a web application
4. **Configure Redirect URI**: Add your Palmr callback URL to authorized redirect URIs
5. **Note Credentials**: Copy the Client ID and Client Secret for Palmr configuration
**Configuration values:**
- **Issuer URL**: `https://accounts.google.com`
- **Scope**: `openid profile email`
### Microsoft Azure AD / Entra ID
1. **Register Application**: Go to Azure Portal > Azure Active Directory > App registrations
2. **Create Registration**: Register a new application with web platform
3. **Configure Authentication**: Add your Palmr callback URL to redirect URIs
4. **Create Secret**: Generate a client secret in Certificates & secrets
5. **Note Configuration**: Copy Application (client) ID and Directory (tenant) ID
**Configuration values:**
- **Issuer URL**: `https://login.microsoftonline.com/{tenant-id}/v2.0`
- **Scope**: `openid profile email`
### Keycloak
1. **Create Client**: In your Keycloak realm, create a new OpenID Connect client
2. **Configure Client**: Set access type to confidential and enable standard flow
3. **Set Redirect URI**: Add your Palmr callback URL to valid redirect URIs
4. **Generate Secret**: Note the client secret from the Credentials tab
**Configuration values:**
- **Issuer URL**: `https://your-keycloak-domain.com/realms/{realm-name}`
- **Scope**: `openid profile email`
![Identity Provider Setup](/assets/v3/oidc/provider-setup.png)
### Zitadel
1. **Create New ProjectApp**: In your desired Zitadel project, create a new application
2. **Name and Type**: Give your application a name and choose **WEB** as the application type
3. **Authentication Method**: Choose Code
4. **Set Redirect URI**: Add your Palmr callback URL to valid redirect URIs
5. **Finish**: After reviewing the configuration create the application
6. **Copy the client ID and client Secrat**: Copy the client id paste it into the **Client ID** of your Palmr OIDC condiguration Form, repeat for the client secret and paste it into the **Client Secret** field
7. **Obtain your Provider URL**: In your Zitadel application go to **URLs** and copy the **Authorization Endpoint (remove the /authorize from that url)** e.g. https://auth.example.com/oauth/v2
**Configuration values:**
- **Issuer URL**: Depends on your Zitadel installation and project. Example: `https://auth.example.com/oauth/v2`
- **Scope**: `openid profile email`
![Zitadel Identity Provider Setup](/assets/v3/oidc/zitadel-provider-setup.png)
---
## Testing OIDC configuration
After configuring OIDC settings, it's important to test the authentication flow to ensure everything works correctly.
### Validation steps
1. **Save Configuration**: Apply your OIDC settings in the Palmr admin panel
2. **Check Status**: Verify that OIDC is enabled and properly configured
3. **Test Login Flow**: Attempt to log in using the OIDC provider
4. **Verify User Creation**: Confirm that user accounts are created or updated correctly
### Testing the authentication flow
1. **Access Login Page**: Navigate to your Palmr login page
2. **OIDC Login Option**: Look for the OIDC/SSO login button or option
3. **Provider Redirect**: Click the OIDC login option to redirect to your identity provider
4. **Authenticate**: Complete authentication with your identity provider
5. **Return to Palmr**: Verify successful redirect back to Palmr with authentication
![OIDC Login Flow](/assets/v3/oidc/login-flow.png)
### Troubleshooting common issues
**Configuration Errors**:
- Verify that all required fields are filled correctly
- Check that the Issuer URL is accessible and returns valid OIDC metadata
- Ensure Client ID and Client Secret match your identity provider configuration
**Redirect URI Mismatches**:
- Confirm that the redirect URI in Palmr matches what's configured in your identity provider
- Check for protocol mismatches (HTTP vs HTTPS)
- Verify that the domain and path are exactly correct
**Authentication Failures**:
- Check that the user exists in your identity provider
- Verify that required scopes are granted
- Ensure the user has necessary permissions in the identity provider
**User Creation Issues**:
- Confirm that auto-registration is enabled if you want new users to be created automatically
- Check that email addresses are provided by the identity provider
- Verify admin domain configuration if users should receive admin privileges
---
## User experience
Once OIDC is properly configured, users will have a seamless authentication experience integrated into Palmr's login flow.
### Login process
1. **Access Palmr**: Users navigate to the Palmr login page
2. **Choose OIDC**: Users select the OIDC/SSO login option
3. **Provider Authentication**: Users are redirected to authenticate with their identity provider
4. **Automatic Return**: After successful authentication, users are automatically redirected back to Palmr
5. **Dashboard Access**: Users gain immediate access to their Palmr dashboard
### User account management
**Automatic Provisioning**: New users are automatically created when they first authenticate via OIDC (if auto-registration is enabled).
**Profile Synchronization**: User profile information (name, email) is synchronized from the identity provider during each login.
**Role Assignment**: User roles and permissions can be automatically assigned based on identity provider attributes or configured rules.
### Account unification
**Email-Based Matching**: If a user authenticates via OIDC using the same email address as an existing credential-based account, both authentication methods will be linked to the same user account.
**Dual Authentication Options**: Users who have both credential-based and OIDC authentication set up can choose either method to log in:
- Traditional email/password authentication
- OIDC/SSO authentication through their identity provider
**Seamless Experience**: Regardless of which authentication method is used, users will access the same account with all their files, shares, and settings preserved.
**Account Consolidation**: This feature ensures that users don't accidentally create duplicate accounts and can transition smoothly between authentication methods as organizational requirements change.
![User Dashboard After OIDC Login](/assets/v3/oidc/user-dashboard.png)
---
## Security considerations
OIDC authentication in Palmr implements several security best practices to ensure safe and secure authentication.
### Security features
**PKCE Flow**: Palmr uses Proof Key for Code Exchange (PKCE) to prevent authorization code interception attacks.
**State Parameter**: Random state parameters are used to prevent CSRF attacks during the authentication flow.
**Token Validation**: All tokens are properly validated according to OIDC specifications.
**Secure Storage**: Sensitive configuration data is securely stored and never exposed to client-side code.
### Best practices
**Use HTTPS**: Always configure Palmr and your identity provider to use HTTPS in production environments.
**Rotate Secrets**: Regularly rotate client secrets and update them in both your identity provider and Palmr configuration.
**Monitor Access**: Regularly review user access and authentication logs to detect any suspicious activity.
**Limit Scopes**: Only request the minimum necessary scopes from your identity provider.
**Validate Domains**: Configure admin email domains carefully to prevent unauthorized privilege escalation.
---
## API endpoints
Palmr provides several API endpoints for OIDC authentication that can be used for integration or troubleshooting.
### Available endpoints
**GET /api/auth/oidc/config**: Retrieve OIDC configuration and status information.
**GET /api/auth/oidc/authorize**: Initiate the OIDC authorization flow.
**GET /api/auth/oidc/callback**: Handle the callback from the identity provider after authentication.
## Finalizing OIDC configuration
After completing the configuration and testing process, your Palmr installation will be ready to handle OIDC authentication seamlessly.
### Configuration completion
Once OIDC is properly configured:
1. **Verify Settings**: Confirm all configuration fields are correct and saved
2. **Test Authentication**: Perform end-to-end testing of the authentication flow
3. **Document Configuration**: Keep a record of your OIDC settings for future reference
4. **Inform Users**: Notify users about the new OIDC authentication option
### Ongoing maintenance
To maintain reliable OIDC authentication:
- **Monitor Authentication**: Regularly check that OIDC authentication is working correctly
- **Update Credentials**: Rotate client secrets periodically for security
- **Review User Access**: Audit user accounts and permissions regularly
- **Stay Updated**: Keep informed about changes to your identity provider's configuration
### Next steps
With OIDC properly configured, your Palmr installation now provides:
- Seamless single sign-on authentication for users
- Centralized user management through your identity provider
- Enhanced security through industry-standard protocols
- Improved user experience with reduced password management
Users can now authenticate using their existing organizational credentials, providing a more streamlined and secure access experience to Palmr's file sharing capabilities.

0
apps/docs/content/docs/3.0-beta/api.mdx → apps/docs/content/docs/3.1-beta/api.mdx
View File

2
apps/docs/content/docs/3.0-beta/architecture.mdx → apps/docs/content/docs/3.1-beta/architecture.mdx
View File

@@ -120,7 +120,7 @@ Palmr. is designed to be flexible in how you handle file storage:
**Optional S3-compatible storage:**
- Enable S3 storage by setting `ENABLE_S3=true`, look at [S3 Providers](/docs/3.0-beta/s3-providers) for more information.
- Enable S3 storage by setting `ENABLE_S3=true`, look at [S3 Providers](/docs/3.1-beta/s3-providers) for more information.
- Compatible with AWS S3, MinIO, and other S3-compatible services
- Ideal for cloud deployments and distributed setups
- Provides additional scalability and redundancy options

0
apps/docs/content/docs/3.0-beta/available-languages.mdx → apps/docs/content/docs/3.1-beta/available-languages.mdx
View File

0
apps/docs/content/docs/3.0-beta/configuring-smtp.mdx → apps/docs/content/docs/3.1-beta/configuring-smtp.mdx
View File

0
apps/docs/content/docs/3.0-beta/contribute.mdx → apps/docs/content/docs/3.1-beta/contribute.mdx
View File

0
apps/docs/content/docs/3.0-beta/gh-sponsor.mdx → apps/docs/content/docs/3.1-beta/gh-sponsor.mdx
View File

0
apps/docs/content/docs/3.0-beta/gh-star.mdx → apps/docs/content/docs/3.1-beta/gh-star.mdx
View File

0
apps/docs/content/docs/3.0-beta/github-architecture.mdx → apps/docs/content/docs/3.1-beta/github-architecture.mdx
View File

0
apps/docs/content/docs/3.0-beta/index.mdx → apps/docs/content/docs/3.1-beta/index.mdx
View File

6
apps/docs/content/docs/3.0-beta/manual-installation.mdx → apps/docs/content/docs/3.1-beta/manual-installation.mdx
View File

@@ -5,7 +5,7 @@ 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.
> **Prefer a quicker setup?** If this hands-on approach feels like overkill, check out our [**Quick Start (Docker)**](/docs/3.1-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:
@@ -233,10 +233,10 @@ pnpm serve
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.
- **Manage Users**: Dive into the [Users Management](/docs/3.1-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.
- **Learn the Internals**: Explore how everything connects in the [Architecture](/docs/3.1-beta/architecture) overview.
Jump into whichever area fits your needs our docs are designed for exploration in any order.

2
apps/docs/content/docs/3.0-beta/meta.json → apps/docs/content/docs/3.1-beta/meta.json
View File

@@ -1,5 +1,5 @@
{
"title": "v3.0-beta",
"title": "v3.1-beta",
"description": "Latest version",
"root": true,
"icon": "Sparkles",

12
apps/docs/content/docs/3.1-beta/oidc-authentication/auth0.mdx Normal file
View File

@@ -0,0 +1,12 @@
---
title: Auth0
icon: Lock
---
## Auth0
### Prerequisites
- Auth0 Application
- Auth0 OAuth Client ID and Secret
- Auth0 OAuth Redirect URI

12
apps/docs/content/docs/3.1-beta/oidc-authentication/authentik.mdx Normal file
View File

@@ -0,0 +1,12 @@
---
title: Authentik
icon: Key
---
## Authentik
### Prerequisites
- Authentik Application
- Authentik OAuth Client ID and Secret
- Authentik OAuth Redirect URI

429
apps/docs/content/docs/3.1-beta/oidc-authentication/discord.mdx Normal file
View File

@@ -0,0 +1,429 @@
---
title: Discord
icon: MessageSquare
---
Discord is one of Palmr's officially supported OIDC providers, offering secure authentication through Discord OAuth 2.0. This integration allows users to sign in to Palmr using their existing Discord accounts, making it perfect for gaming communities, developer teams, and organizations already using Discord.
{/* Imagem: Screenshot da tela de login do Palmr mostrando o botão "Sign in with Discord" em destaque */}
## Why use Discord authentication?
Discord authentication provides several advantages for community-focused organizations and teams:
- **Community integration** - Perfect for gaming communities and Discord-centric organizations
- **Familiar experience** - Users already trust and use Discord daily
- **Rich user profiles** - Access to Discord usernames, avatars, and global names
- **Developer-friendly** - Great for technical teams and open-source projects
- **No additional accounts** - Users can access Palmr without creating new credentials
---
## Prerequisites
Before configuring Discord authentication, ensure you have:
- **Discord Developer Portal access** - Ability to create applications on Discord
- **Admin privileges in Palmr** - Required to configure OIDC settings
- **Server ownership or permissions** - If integrating with a Discord server
> **Note:** Discord is pre-configured as an official provider in Palmr, which means the technical configuration is handled automatically. You only need to provide your OAuth credentials.
---
## Setting up Discord Developer Portal
### Creating a Discord application
To get started with Discord authentication, you'll need to create an application in Discord Developer Portal.
1. **Navigate to Discord Developer Portal**: Go to [discord.com/developers/applications](https://discord.com/developers/applications)
{/* Imagem: Screenshot da página inicial do Discord Developer Portal com botão "New Application" em destaque */}
2. **Create new application**: Click **"New Application"** button
3. **Enter application details**:
- **Name**: Enter a descriptive name like "Palmr File Sharing"
- **Team**: Select your team (or leave as personal)
{/* Imagem: Modal de criação de aplicação no Discord com campos preenchidos */}
4. **Create application**: Click **"Create"** to generate your application
### Configuring application settings
After creating your application, you'll need to configure basic settings and branding.
1. **Update application information**:
- **Description**: Add a clear description of your Palmr instance
- **Icon**: Upload your organization's logo or Palmr-related icon
- **Cover Image**: Optional banner image for better branding
{/* Imagem: Página de configurações gerais da aplicação Discord com campos preenchidos */}
2. **Configure application details**:
- **Tags**: Add relevant tags (optional)
- **Privacy Policy URL**: Add your privacy policy URL if required
- **Terms of Service URL**: Add your terms of service URL if required
### Setting up OAuth2 configuration
Now you'll configure the OAuth2 settings that Palmr will use to authenticate users.
1. **Navigate to OAuth2**: In the left sidebar, click **"OAuth2"** > **"General"**
{/* Imagem: Menu lateral do Discord Developer Portal com "OAuth2" expandido e "General" em destaque */}
2. **Configure OAuth2 settings**:
- **Client Secret**: Click **"Reset Secret"** to generate a new client secret
- **Copy credentials**: Save both **Client ID** and **Client Secret** for later use
{/* Imagem: Seção OAuth2 General mostrando Client ID visível e botão "Reset Secret" para gerar Client Secret */}
3. **Add redirect URIs**: In the **"Redirects"** section, add your Palmr callback URLs:
**For production:**
```
https://yourdomain.com/api/auth/callback/discord
```
**For development:**
```
http://localhost:3000/api/auth/callback/discord
```
**For custom ports:**
```
https://yourdomain.com:5487/api/auth/callback/discord
```
{/* Imagem: Campo "Redirects" preenchido com as URLs de callback do Palmr para Discord */}
4. **Save changes**: Click **"Save Changes"** to apply your configuration
### Configuring OAuth2 scopes
Discord uses specific scopes to control what information your application can access.
1. **Navigate to OAuth2 URL Generator**: Click **"OAuth2"** > **"URL Generator"**
{/* Imagem: Página URL Generator do Discord OAuth2 mostrando lista de scopes disponíveis */}
2. **Select required scopes**:
- **`identify`** - Access to user's basic account information (required)
- **`email`** - Access to user's email address (required for Palmr)
{/* Imagem: Scopes "identify" e "email" selecionados no Discord URL Generator */}
3. **Verify permissions**: Review what each scope provides:
- **identify**: Username, discriminator, global name, avatar
- **email**: Email address for account creation and management
> **Important:** Palmr requires both `identify` and `email` scopes to function properly. The `identify` scope provides user identification, while `email` is needed for account creation and management.
---
## Configuring Palmr
### Accessing OIDC settings
To configure Discord authentication in Palmr, you need administrator access to the settings panel.
1. **Login as administrator**: Sign in to Palmr with an admin account
{/* Imagem: Tela de login do Palmr com credenciais de administrador */}
2. **Access settings**: Click your profile picture in the header and select **Settings**
{/* Imagem: Menu dropdown do usuário no Palmr com a opção "Settings" em destaque */}
3. **Navigate to authentication**: Find and click on the **Authentication** or **OIDC** configuration section
{/* Imagem: Página de configurações do Palmr mostrando as diferentes seções, com Authentication/OIDC em destaque */}
### Enabling Discord provider
Discord comes pre-configured as an official provider, so the setup process is streamlined.
1. **Locate Discord provider**: Find Discord in the list of available providers
{/* Imagem: Lista de provedores OIDC no Palmr com o Discord listado como provider oficial */}
2. **Enable the provider**: Toggle the status to **Enabled**
{/* Imagem: Card do provedor Discord no Palmr com o toggle "Enabled" ativado */}
3. **Configure credentials**:
- **Client ID**: Paste the Client ID from Discord Developer Portal
- **Client Secret**: Paste the Client Secret from Discord Developer Portal
{/* Imagem: Formulário de configuração do Discord provider no Palmr com os campos Client ID e Client Secret preenchidos */}
### Advanced configuration options
Configure additional settings to customize the authentication behavior:
**Auto Registration**: Enable this to automatically create user accounts when someone authenticates for the first time.
**Admin Email Domains**: Specify domains that should automatically receive admin privileges. This is less common with Discord since users often use personal emails.
**Sort Order**: Control where the Discord login button appears relative to other authentication providers.
{/* Imagem: Seção de configurações avançadas do Discord provider mostrando Auto Registration e Sort Order */}
> **Community tip:** Discord authentication works great for gaming communities and development teams. Consider enabling auto-registration for trusted Discord communities.
---
## Technical configuration
Discord's technical configuration is handled automatically, but understanding the setup can help with troubleshooting:
```yaml
Provider Type: OAuth 2.0 (No OIDC Discovery)
Issuer URL: https://discord.com
Authorization Endpoint: /oauth2/authorize
Token Endpoint: /api/oauth2/token
UserInfo Endpoint: /api/users/@me
Scopes: identify email
Discovery: Disabled (Manual endpoint configuration)
```
### Field mappings
Palmr automatically maps Discord user information to local user accounts:
- **User ID**: Maps from Discord's `id` field
- **Email**: Maps from Discord's `email` field
- **Display Name**: Maps from Discord's `global_name` or falls back to `username`
- **Username**: Maps from Discord's `username` field
- **Avatar**: Maps from Discord's `avatar` field (processed as Discord CDN URL)
### Discord-specific features
- **Global Names**: Supports Discord's new global name system while maintaining compatibility with legacy usernames
- **Avatar Processing**: Automatically constructs Discord CDN URLs for user avatars
- **No Discovery**: Uses manually configured endpoints for better reliability
---
## Testing the configuration
### Verifying the setup
After configuring Discord authentication, test the integration to ensure everything works correctly.
1. **Check login page**: Navigate to your Palmr login page and verify the "Sign in with Discord" button appears
{/* Imagem: Tela de login do Palmr mostrando o botão "Sign in with Discord" visível e funcionando */}
2. **Test authentication flow**: Click the Discord sign-in button and complete the authentication process
{/* Imagem: Fluxo de autenticação do Discord mostrando a tela de autorização do Discord após clicar no botão */}
3. **Verify user creation**: Confirm that a new user account is created (if auto-registration is enabled)
{/* Imagem: Dashboard administrativo do Palmr mostrando o novo usuário criado automaticamente via Discord */}
4. **Check user information**: Verify that Discord username, global name, and avatar are properly imported
### Login flow verification
The complete authentication process should work as follows:
1. **User clicks "Sign in with Discord"**: The browser redirects to Discord's authorization page
2. **User authorizes application**: User grants permissions for `identify` and `email` scopes
3. **Discord redirects back to Palmr**: User returns to Palmr with authentication tokens
4. **Palmr creates or updates user**: User account is automatically managed with Discord information
5. **User accesses Palmr**: User is logged in with their Discord identity
{/* Imagem: Diagrama de fluxo visual mostrando o processo completo de autenticação Discord -> Palmr */}
---
## Troubleshooting common issues
### Invalid redirect URI error
**Error message**: `invalid_redirect_uri`
{/* Imagem: Screenshot do erro "invalid_redirect_uri" no Discord durante tentativa de login */}
**Cause**: The redirect URI in your request doesn't match what's configured in Discord Developer Portal.
**Solution**:
1. Check the exact URL in the error message
2. Add this exact URL to your Discord application's redirect URIs
3. Ensure you include the correct protocol (http/https) and port
4. Remove any trailing slashes unless they're in the callback URL
### Access denied error
**Error message**: `access_denied`
{/* Imagem: Screenshot do erro "access_denied" na tela de autorização do Discord */}
**Cause**: User denied permissions or the application doesn't have required scopes.
**Solution**:
1. Verify that your Discord application requests `identify` and `email` scopes
2. Check that users are granting permissions during the authorization flow
3. Ensure your application is not restricted or disabled in Discord Developer Portal
4. Verify the application has proper permissions set up
### Invalid client error
**Error message**: `invalid_client`
{/* Imagem: Screenshot do erro "invalid_client" durante tentativa de autenticação com Discord */}
**Cause**: Incorrect Client ID or Client Secret.
**Solution**:
1. Double-check that you've copied the credentials correctly from Discord Developer Portal
2. Ensure there are no extra spaces or characters in the credentials
3. Generate a new Client Secret if necessary
4. Verify you're using the correct application in Discord Developer Portal
### Missing email scope error
**Error message**: Email not provided or scope missing
{/* Imagem: Interface do Discord Developer Portal mostrando configuração de scopes com "email" em destaque */}
**Cause**: Discord application not configured with email scope or user's email is not verified.
**Solution**:
1. Verify that your Discord application requests the `email` scope
2. Check that users have verified their email addresses on Discord
3. Ensure the scope configuration matches what Palmr expects
4. Test with a Discord account that has a verified email
### User information not displaying correctly
**Cause**: Discord username/global name mapping issues.
**Solution**:
1. Check that the user has set a global name in Discord (new feature)
2. Verify field mappings are working correctly in Palmr logs
3. Test with different Discord accounts (some may have legacy usernames)
4. Update user information manually through Palmr admin interface if needed
---
## Security best practices
### Application security
- **Keep secrets secure**: Never expose your Client Secret in client-side code or public repositories
- **Rotate credentials regularly**: Generate new Client Secrets periodically for enhanced security
- **Use environment variables**: Store sensitive configuration in environment variables
- **Monitor application usage**: Regularly check Discord Developer Portal for unusual activity
### Scope and permission management
- **Minimal scopes**: Only request `identify` and `email` scopes as required by Palmr
- **User consent**: Ensure users understand what permissions they're granting
- **Regular audits**: Review which users have connected their Discord accounts
- **Access reviews**: Periodically check user access and remove inactive accounts
### Production considerations
- **Use HTTPS**: Always use HTTPS in production environments
- **Configure proper domains**: Use production domains in Discord redirect URIs
- **Test thoroughly**: Verify the complete authentication flow before going live
- **Monitor logs**: Keep track of authentication attempts and errors
---
## Example configurations
### Gaming community setup
For a gaming community using Discord:
```yaml
Discord Developer Portal:
Application: Gaming Community Files
Description: File sharing for our gaming community
Redirect URIs: https://files.gamingcommunity.com/api/auth/callback/discord
Scopes: identify, email
Palmr Configuration:
Provider: Discord (Enabled)
Auto Register: Yes
Admin Domains: (leave empty - use manual promotion)
Client ID: 1234567890123456789
Client Secret: abcdefghijklmnopqrstuvwxyz123456
```
{/* Imagem: Configuração completa para comunidade gaming mostrando Discord Developer Portal e Palmr lado a lado */}
### Development team setup
For a software development team:
```yaml
Discord Developer Portal:
Application: DevTeam File Sharing
Description: Secure file sharing for development team
Redirect URIs:
- https://files.devteam.com/api/auth/callback/discord
- http://localhost:3000/api/auth/callback/discord
Scopes: identify, email
Palmr Configuration:
Provider: Discord (Enabled)
Auto Register: Yes
Admin Domains: devteam.com
Client ID: 9876543210987654321
Client Secret: zyxwvutsrqponmlkjihgfedcba654321
```
{/* Imagem: Configuração para equipe de desenvolvimento com múltiplos ambientes (produção e desenvolvimento) */}
---
## Discord vs other providers
### When to choose Discord
- **Gaming communities**: Perfect for organizations centered around gaming
- **Developer teams**: Great for technical teams already using Discord
- **Community-driven projects**: Ideal for open-source projects with Discord communities
- **Informal organizations**: Better suited for casual, community-based groups
### Considerations
- **Limited business features**: Discord lacks enterprise features like SSO management
- **Personal accounts**: Users typically use personal Discord accounts, not business emails
- **Community focus**: Better for communities than traditional business environments
- **User demographics**: Appeals more to younger, tech-savvy user bases
---
## Next steps
With Discord authentication configured, you might want to:
- **Customize user experience**: Adapt Palmr's interface for your Discord community
- **Set up community integrations**: Consider Discord bot integrations for notifications
- **Configure additional providers**: Add other providers for users who don't use Discord
- **Monitor community engagement**: Track how your Discord community uses Palmr
For more information about OIDC authentication in Palmr, see the [OIDC Authentication overview](/docs/3.1-beta/oidc-authentication).
## Useful resources
- [Discord Developer Documentation](https://discord.com/developers/docs)
- [Discord OAuth2 Guide](https://discord.com/developers/docs/topics/oauth2)
- [Discord Applications](https://discord.com/developers/applications)
- [Discord API Reference](https://discord.com/developers/docs/reference)

12
apps/docs/content/docs/3.1-beta/oidc-authentication/frontegg.mdx Normal file
View File

@@ -0,0 +1,12 @@
---
title: Frontegg
icon: Egg
---
## Frontegg
### Prerequisites
- Frontegg Application
- Frontegg OAuth Client ID and Secret
- Frontegg OAuth Redirect URI

12
apps/docs/content/docs/3.1-beta/oidc-authentication/github.mdx Normal file
View File

@@ -0,0 +1,12 @@
---
title: GitHub
icon: Github
---
## GitHub
### Prerequisites
- GitHub Application
- GitHub OAuth Client ID and Secret
- GitHub OAuth Redirect URI

408
apps/docs/content/docs/3.1-beta/oidc-authentication/google.mdx Normal file
View File

@@ -0,0 +1,408 @@
---
title: Google
icon: Chrome
---
Google is one of Palmr's officially supported OIDC providers, offering secure and reliable authentication through Google OAuth 2.0. This integration allows users to sign in to Palmr using their existing Google accounts, providing a seamless single sign-on experience.
{/* Imagem: Screenshot da tela de login do Palmr mostrando o botão "Sign in with Google" em destaque */}
## Why use Google authentication?
Google authentication provides several advantages for both administrators and users:
- **Seamless login experience** - Users can access Palmr with their existing Google accounts
- **Enhanced security** - Leverage Google's robust security infrastructure and two-factor authentication
- **Reduced password fatigue** - No need to create and remember additional passwords
- **Enterprise integration** - Perfect for organizations already using Google Workspace
- **Automatic user provisioning** - New users are created automatically upon first login
---
## Prerequisites
Before configuring Google authentication, ensure you have:
- **Google Cloud Console access** - Ability to create and manage projects
- **Admin privileges in Palmr** - Required to configure OIDC settings
- **Domain ownership** - For production deployments with custom domains
> **Note:** Google is pre-configured as an official provider in Palmr, which means the technical configuration is handled automatically. You only need to provide your OAuth credentials.
---
## Setting up Google Cloud Console
### Creating a Google Cloud project
To get started with Google authentication, you'll need to set up a project in Google Cloud Console.
1. **Navigate to Google Cloud Console**: Go to [console.cloud.google.com](https://console.cloud.google.com/)
{/* Imagem: Screenshot da página inicial do Google Cloud Console com a seleção de projeto em destaque */}
2. **Create or select a project**: Choose an existing project or create a new one for your Palmr installation
{/* Imagem: Modal de criação/seleção de projeto no Google Cloud Console, mostrando o botão "NEW PROJECT" */}
3. **Enable the project**: Ensure the project is active and selected
### Configuring OAuth consent screen
The OAuth consent screen is what users see when they authenticate with Google.
1. **Access OAuth consent screen**: Navigate to **APIs & Services** > **OAuth consent screen**
{/* Imagem: Menu lateral do Google Cloud Console com "APIs & Services" expandido e "OAuth consent screen" em destaque */}
2. **Choose user type**:
- **Internal** - For Google Workspace organizations (users within your domain only)
- **External** - For public use (any Google user can authenticate)
{/* Imagem: Tela de seleção do tipo de usuário (Internal vs External) no OAuth consent screen */}
3. **Fill required information**:
- **Application name**: Enter a descriptive name like "Palmr File Sharing"
- **User support email**: Provide a valid support email address
- **Developer contact information**: Add your contact email for Google communications
{/* Imagem: Formulário do OAuth consent screen preenchido com os campos obrigatórios destacados */}
> **Tip:** For business use, choose "Internal" if you have Google Workspace. This restricts access to your organization's users and simplifies the approval process.
### Adding OAuth scopes
Configure the permissions your application will request from users.
1. **Navigate to Scopes**: In the OAuth consent screen configuration, find the **Scopes** section
2. **Add standard scopes**:
- `openid` - Required for OpenID Connect
- `profile` - Access to basic profile information
- `email` - Access to user's email address
{/* Imagem: Seção de Scopes no OAuth consent screen com os scopes openid, profile e email adicionados */}
These scopes provide Palmr with the basic information needed to create and manage user accounts.
### Creating OAuth 2.0 credentials
Now you'll create the actual credentials that Palmr will use to authenticate with Google.
1. **Navigate to Credentials**: Go to **APIs & Services** > **Credentials**
{/* Imagem: Página de Credentials no Google Cloud Console vazia, pronta para criar novas credenciais */}
2. **Create OAuth client**: Click **+ CREATE CREDENTIALS** > **OAuth client ID**
{/* Imagem: Dropdown do botão "CREATE CREDENTIALS" com "OAuth client ID" em destaque */}
3. **Select application type**: Choose **Web application**
{/* Imagem: Formulário de criação de OAuth client ID com "Web application" selecionado */}
4. **Configure authorized URIs**:
**For production:**
```
https://yourdomain.com/api/auth/callback/google
```
**For development:**
```
http://localhost:3000/api/auth/callback/google
```
**For custom ports:**
```
https://yourdomain.com:5487/api/auth/callback/google
```
{/* Imagem: Campo "Authorized redirect URIs" preenchido com as URLs de callback do Palmr */}
5. **Create and save credentials**: Click **Create** and copy both the **Client ID** and **Client Secret**
{/* Imagem: Modal final mostrando o Client ID e Client Secret gerados, com botões de cópia em destaque */}
> **Important:** Replace `yourdomain.com` with your actual domain. You can add multiple URIs for different environments (development, staging, production).
---
## Configuring Palmr
### Accessing OIDC settings
To configure Google authentication in Palmr, you need administrator access to the settings panel.
1. **Login as administrator**: Sign in to Palmr with an admin account
{/* Imagem: Tela de login do Palmr com credenciais de administrador */}
2. **Access settings**: Click your profile picture in the header and select **Settings**
{/* Imagem: Menu dropdown do usuário no Palmr com a opção "Settings" em destaque */}
3. **Navigate to authentication**: Find and click on the **Authentication** or **OIDC** configuration section
{/* Imagem: Página de configurações do Palmr mostrando as diferentes seções, com Authentication/OIDC em destaque */}
### Enabling Google provider
Google comes pre-configured as an official provider, so the setup process is streamlined.
1. **Locate Google provider**: Find Google in the list of available providers
{/* Imagem: Lista de provedores OIDC no Palmr com o Google listado como provider oficial */}
2. **Enable the provider**: Toggle the status to **Enabled**
{/* Imagem: Card do provedor Google no Palmr com o toggle "Enabled" ativado */}
3. **Configure credentials**:
- **Client ID**: Paste the Client ID from Google Cloud Console
- **Client Secret**: Paste the Client Secret from Google Cloud Console
{/* Imagem: Formulário de configuração do Google provider no Palmr com os campos Client ID e Client Secret preenchidos */}
### Advanced configuration options
Configure additional settings to customize the authentication behavior:
**Auto Registration**: Enable this to automatically create user accounts when someone authenticates for the first time.
**Admin Email Domains**: Specify domains that should automatically receive admin privileges. For example, entering `yourcompany.com` will grant admin access to anyone with an email from that domain.
**Sort Order**: Control where the Google login button appears relative to other authentication providers.
{/* Imagem: Seção de configurações avançadas do Google provider mostrando Auto Registration, Admin Email Domains e Sort Order */}
> **Security consideration:** Be cautious with auto-registration and admin domains. Only enable these if you trust the user base or have domain restrictions in place.
---
## Technical configuration
Google's technical configuration is handled automatically, but understanding the setup can help with troubleshooting:
```yaml
Provider Type: OAuth 2.0 with OIDC Discovery
Issuer URL: https://accounts.google.com
Authorization Endpoint: /o/oauth2/v2/auth
Token Endpoint: /o/oauth2/token
UserInfo Endpoint: https://www.googleapis.com/oauth2/v3/userinfo
Scopes: openid profile email
Discovery: Enabled (/.well-known/openid_configuration)
```
### Field mappings
Palmr automatically maps Google user information to local user accounts:
- **User ID**: Maps from Google's `sub` field
- **Email**: Maps from Google's `email` field
- **Full Name**: Maps from Google's `name` field
- **First Name**: Maps from Google's `given_name` field
- **Last Name**: Maps from Google's `family_name` field
- **Avatar**: Maps from Google's `picture` field
---
## Testing the configuration
### Verifying the setup
After configuring Google authentication, test the integration to ensure everything works correctly.
1. **Check login page**: Navigate to your Palmr login page and verify the "Sign in with Google" button appears
{/* Imagem: Tela de login do Palmr mostrando o botão "Sign in with Google" visível e funcionando */}
2. **Test authentication flow**: Click the Google sign-in button and complete the authentication process
{/* Imagem: Fluxo de autenticação do Google mostrando a tela de login do Google após clicar no botão */}
3. **Verify user creation**: Confirm that a new user account is created (if auto-registration is enabled)
{/* Imagem: Dashboard administrativo do Palmr mostrando o novo usuário criado automaticamente via Google */}
4. **Check admin privileges**: If you configured admin domains, verify that users from those domains receive admin access
### Login flow verification
The complete authentication process should work as follows:
1. **User clicks "Sign in with Google"**: The browser redirects to Google's authentication page
2. **User authenticates with Google**: User enters their Google credentials or confirms existing session
3. **Google redirects back to Palmr**: User returns to Palmr with authentication tokens
4. **Palmr creates or updates user**: User account is automatically managed based on your configuration
5. **User accesses Palmr**: User is logged in and can use all features according to their permissions
{/* Imagem: Diagrama de fluxo visual mostrando o processo completo de autenticação Google -> Palmr */}
---
## Troubleshooting common issues
### Redirect URI mismatch error
**Error message**: `Error 400: redirect_uri_mismatch`
{/* Imagem: Screenshot do erro "redirect_uri_mismatch" no browser durante tentativa de login */}
**Cause**: The redirect URI in your request doesn't match what's configured in Google Cloud Console.
**Solution**:
1. Check the exact URL in the error message
2. Add this exact URL to your Google Cloud Console credentials
3. Ensure you include the correct protocol (http/https) and port
4. Remove any trailing slashes unless they're in the error message
### Access denied error
**Error message**: `Error 403: access_denied`
{/* Imagem: Screenshot do erro "access_denied" na tela de OAuth do Google */}
**Cause**: User denied permissions or the OAuth consent screen isn't properly configured.
**Solution**:
1. Verify the OAuth consent screen is published (for External user type)
2. Check that required scopes are correctly configured
3. For Internal applications, ensure the user belongs to your Google Workspace organization
4. Review and simplify the permissions you're requesting
### Invalid client error
**Error message**: `Error 401: invalid_client`
{/* Imagem: Screenshot do erro "invalid_client" durante tentativa de autenticação */}
**Cause**: Incorrect Client ID or Client Secret.
**Solution**:
1. Double-check that you've copied the credentials correctly from Google Cloud Console
2. Ensure there are no extra spaces or characters in the credentials
3. Regenerate credentials if necessary
4. Verify you're using the correct project in Google Cloud Console
### Users not receiving admin privileges
**Cause**: Email domain not properly configured in Palmr settings.
{/* Imagem: Configuração de Admin Email Domains no Palmr com exemplo de domínio configurado */}
**Solution**:
1. Verify the admin domain configuration in Palmr settings
2. Check that the user's email domain exactly matches the configured domain
3. Ensure the domain format is correct (e.g., `company.com`, not `@company.com`)
4. Manually promote users through the admin interface if needed
### Discovery endpoint issues
**Cause**: Network connectivity problems or DNS resolution issues.
**Solution**:
1. Test the discovery endpoint manually: `https://accounts.google.com/.well-known/openid_configuration`
2. Check server firewall and network connectivity
3. Verify DNS resolution from your server
4. Consider proxy or CDN configurations that might block the request
---
## Security best practices
### Credential management
- **Never expose secrets**: Keep your Client Secret secure and never commit it to version control
- **Rotate credentials regularly**: Generate new credentials periodically for enhanced security
- **Use environment variables**: Store sensitive configuration in environment variables, not config files
- **Monitor access logs**: Regularly review authentication logs for suspicious activity
### Domain and user restrictions
- **Limit admin domains**: Only add trusted domains to the admin list
- **Review auto-registration**: Consider disabling auto-registration if you need manual user approval
- **Use Internal OAuth**: For organizations with Google Workspace, use Internal OAuth consent screen
- **Regular access reviews**: Periodically review user access and remove inactive accounts
### Production considerations
- **Use HTTPS**: Always use HTTPS in production environments
- **Configure proper domains**: Use production domains in Google Cloud Console
- **Test thoroughly**: Verify the complete authentication flow before going live
- **Plan for failures**: Have fallback authentication methods available
---
## Example configurations
### Basic setup
For a simple Palmr installation with Google authentication:
```yaml
Google Cloud Console:
Project: palmr-production
OAuth Consent: External
Scopes: openid, profile, email
Authorized URIs: https://files.yourcompany.com/api/auth/callback/google
Palmr Configuration:
Provider: Google (Enabled)
Auto Register: Yes
Admin Domains: yourcompany.com
Client ID: 123456789-abcdefghijklmnop.apps.googleusercontent.com
Client Secret: GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx
```
{/* Imagem: Comparação lado a lado das configurações no Google Cloud Console e no Palmr para setup básico */}
### Enterprise setup
For Google Workspace organizations:
```yaml
Google Cloud Console:
Project: yourcompany-palmr
OAuth Consent: Internal
Scopes: openid, profile, email
Authorized URIs:
- https://palmr.yourcompany.com/api/auth/callback/google
- https://files.yourcompany.com/api/auth/callback/google
Palmr Configuration:
Provider: Google (Enabled)
Auto Register: Yes
Admin Domains: yourcompany.com, admin.yourcompany.com
Client ID: 987654321-zyxwvutsrqponmlk.apps.googleusercontent.com
Client Secret: GOCSPX-yyyyyyyyyyyyyyyyyyyyyyyy
```
{/* Imagem: Configuração enterprise completa mostrando múltiplos domínios e URIs autorizadas */}
---
## Next steps
With Google authentication configured, you might want to:
- **Configure additional providers**: Set up other OIDC providers for more authentication options
- **Customize user management**: Fine-tune auto-registration and admin assignment rules
- **Review security settings**: Ensure your authentication setup meets your security requirements
- **Monitor usage**: Keep track of authentication patterns and user activity
For more information about OIDC authentication in Palmr, see the [OIDC Authentication overview](/docs/3.1-beta/oidc-authentication).
## Useful resources
- [Google Identity Platform Documentation](https://developers.google.com/identity)
- [OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server)
- [OpenID Connect](https://developers.google.com/identity/protocols/oauth2/openid-connect)
- [Google Cloud Console](https://console.cloud.google.com/apis/credentials)

72
apps/docs/content/docs/3.1-beta/oidc-authentication/index.mdx Normal file
View File

@@ -0,0 +1,72 @@
---
title: Introduction
icon: IdCard
---
Palmr supports OpenID Connect (OIDC) authentication, allowing users to sign in using external identity providers such as Google, Zitadel, Auth0, and other OIDC-compliant services. This feature provides seamless single sign-on (SSO) capabilities and centralized user management.
OIDC authentication in Palmr is built using the industry-standard OpenID Connect protocol. The implementation supports automatic user provisioning, and flexible configuration options.
## Why use OIDC authentication?
OIDC authentication provides several advantages for organizations and users:
**Centralized Authentication**: Users can authenticate using their existing organizational credentials without creating separate accounts for Palmr.
**Enhanced Security**: OIDC provides robust security features including token-based authentication, PKCE flow, and standardized protocols.
**Single Sign-On**: Users can access Palmr. seamlessly if they're already authenticated with their identity provider.
**User Management**: Administrators can manage user access centrally through their existing identity provider.
**Compliance**: OIDC helps meet organizational security and compliance requirements by leveraging existing identity infrastructure.
---
## Prerequisites
Before configuring OIDC authentication, ensure you have:
- **Administrative Access**: ADMIN privileges in Palmr. to configure OIDC settings
- **Identity Provider**: An OIDC-compliant identity provider (Google, Zitadel, Auth0, etc.)
- **Application Registration**: Your Palmr. application registered with your identity provider
- **OIDC Credentials**: Client ID, Client Secret, and Issuer URL from your identity provider
### Supported identity providers
Palmr's OIDC implementation is compatible with any OpenID Connect compliant provider, including as official providers:
- **Google**
- **Discord**
- **Github**
- **Zitadel**
- **Auth0**
- **Authentik**
- **Frontegg**
- **Kinde Auth**
Although these are the official providers (internally tested with 100% success), you can connect any OIDC provider by providing your credentials and connection URL. We've developed a practical way to integrate virtually all OIDC providers available in the market. In this documentation, you can consult how to configure each of the official providers, as well as include other providers not listed as official. Just below, you will find instructions on how to access the OIDC provider configuration. For specific details about configuring each provider, select the desired option in the sidebar, in the "OIDC Authentication" section.
---
## Configuring OIDC settings
OIDC configuration is managed through Palmr's administrative settings panel, accessible only to users with ADMIN privileges.
### Accessing OIDC configuration
To configure OIDC authentication:
1. **Access Settings**: Click on your profile picture in the header and select **Settings**
2. **Navigate to Authentication**: Find the **Authentication** or **OIDC** configuration section
3. **Enable OIDC**: Toggle the OIDC authentication option to enable it
{/* imagem do novo oconfig de OIDC */}
---
## Next steps
Select one of the cards below to continue configuring your authentication provider.
<OIDCProviderCards />

12
apps/docs/content/docs/3.1-beta/oidc-authentication/kinde-auth.mdx Normal file
View File

@@ -0,0 +1,12 @@
---
title: Kinde Auth
icon: Users
---
## Kinde Auth
### Prerequisites
- Kinde Auth Application
- Kinde Auth OAuth Client ID and Secret
- Kinde Auth OAuth Redirect URI

17
apps/docs/content/docs/3.1-beta/oidc-authentication/meta.json Normal file
View File

@@ -0,0 +1,17 @@
{
"title": "OIDC Authentication",
"icon": "Key",
"pages": [
"index",
"google",
"discord",
"github",
"zitadel",
"auth0",
"authentik",
"frontegg",
"kinde-auth",
"other"
],
"defaultOpen": false
}

11
apps/docs/content/docs/3.1-beta/oidc-authentication/other.mdx Normal file
View File

@@ -0,0 +1,11 @@
---
title: Other Providers
icon: Settings
---
## Other
### Prerequisites
- Other OAuth Client ID and Secret
- Other OAuth Redirect URI

12
apps/docs/content/docs/3.1-beta/oidc-authentication/zitadel.mdx Normal file
View File

@@ -0,0 +1,12 @@
---
title: Zitadel
icon: Shield
---
## Zitadel
### Prerequisites
- Zitadel Application
- Zitadel OAuth Client ID and Secret
- Zitadel OAuth Redirect URI

0
apps/docs/content/docs/3.0-beta/open-an-issue.mdx → apps/docs/content/docs/3.1-beta/open-an-issue.mdx
View File

0
apps/docs/content/docs/3.0-beta/password-reset-without-smtp.mdx → apps/docs/content/docs/3.1-beta/password-reset-without-smtp.mdx
View File

16
apps/docs/content/docs/3.0-beta/quick-start.mdx → apps/docs/content/docs/3.1-beta/quick-start.mdx
View File

@@ -112,7 +112,7 @@ services:
docker-compose up -d
```
> **Permission Configuration**: If you encounter permission issues with bind mounts (common on NAS systems), see our [UID/GID Configuration](/docs/3.0-beta/uid-gid-configuration) guide for automatic permission handling.
> **Permission Configuration**: If you encounter permission issues with bind mounts (common on NAS systems), see our [UID/GID Configuration](/docs/3.1-beta/uid-gid-configuration) guide for automatic permission handling.
---
@@ -128,7 +128,7 @@ Configure Palmr. behavior through environment variables:
> **⚠️ Security Warning**: Always change the `ENCRYPTION_KEY` in production. This key encrypts your files - losing it makes files permanently inaccessible.
> **🔗 Reverse Proxy**: If deploying behind a reverse proxy (Traefik, Nginx, etc.), set `SECURE_SITE=true` and review our [Reverse Proxy Configuration](/docs/3.0-beta/reverse-proxy-configuration) guide for proper setup.
> **🔗 Reverse Proxy**: If deploying behind a reverse proxy (Traefik, Nginx, etc.), set `SECURE_SITE=true` and review our [Reverse Proxy Configuration](/docs/3.1-beta/reverse-proxy-configuration) guide for proper setup.
### Generate Secure Encryption Keys
@@ -152,7 +152,7 @@ If you exposed port 3333 in your configuration, you can also access:
- **API Documentation**: `http://localhost:3333/docs` (local) or `http://YOUR_SERVER_IP:3333/docs` (server)
- **API Endpoints**: Available at `http://localhost:3333` (local) or `http://YOUR_SERVER_IP:3333` (server)
> **📚 Learn More**: For complete API documentation, authentication, and integration examples, see our [API Reference](/docs/3.0-beta/api) guide.
> **📚 Learn More**: For complete API documentation, authentication, and integration examples, see our [API Reference](/docs/3.1-beta/api) guide.
> **💡 Production Tip**: For production deployments, configure HTTPS with a valid SSL certificate for enhanced security.
@@ -245,14 +245,14 @@ Your Palmr. instance is now ready! Explore additional configuration options:
### Advanced Configuration
- **[UID/GID Configuration](/docs/3.0-beta/uid-gid-configuration)** - Configure user permissions for NAS systems and custom environments
- **[S3 Storage](/docs/3.0-beta/s3-configuration)** - Scale with Amazon S3 or compatible storage providers
- **[Manual Installation](/docs/3.0-beta/manual-installation)** - Manual installation and custom configurations
- **[UID/GID Configuration](/docs/3.1-beta/uid-gid-configuration)** - Configure user permissions for NAS systems and custom environments
- **[S3 Storage](/docs/3.1-beta/s3-configuration)** - Scale with Amazon S3 or compatible storage providers
- **[Manual Installation](/docs/3.1-beta/manual-installation)** - Manual installation and custom configurations
### Integration & Development
- **[API Reference](/docs/3.0-beta/api)** - Integrate Palmr. with your applications
- **[Architecture Guide](/docs/3.0-beta/architecture)** - Understanding Palmr. components and design
- **[API Reference](/docs/3.1-beta/api)** - Integrate Palmr. with your applications
- **[Architecture Guide](/docs/3.1-beta/architecture)** - Understanding Palmr. components and design
---

2
apps/docs/content/docs/3.0-beta/reverse-proxy-configuration.mdx → apps/docs/content/docs/3.1-beta/reverse-proxy-configuration.mdx
View File

@@ -131,7 +131,7 @@ environment:
- ENCRYPTION_KEY=your-key-here
```
> **💡 Note**: Check your host UID/GID with `id` command and use those values. See [UID/GID Configuration](/docs/3.0-beta/uid-gid-configuration) for detailed setup.
> **💡 Note**: Check your host UID/GID with `id` command and use those values. See [UID/GID Configuration](/docs/3.1-beta/uid-gid-configuration) for detailed setup.
---

0
apps/docs/content/docs/3.0-beta/s3-providers.mdx → apps/docs/content/docs/3.1-beta/s3-providers.mdx
View File

0
apps/docs/content/docs/3.0-beta/screenshots.mdx → apps/docs/content/docs/3.1-beta/screenshots.mdx
View File

0
apps/docs/content/docs/3.0-beta/translation-management.mdx → apps/docs/content/docs/3.1-beta/translation-management.mdx
View File

0
apps/docs/content/docs/3.0-beta/uid-gid-configuration.mdx → apps/docs/content/docs/3.1-beta/uid-gid-configuration.mdx
View File

5
apps/docs/content/docs/meta.json
View File

@@ -1,7 +1,6 @@
{
"pages": [
"3.0-beta",
"2.0.0-beta",
"1.1.7-beta"
"3.1-beta",
"2.0.0-beta"
]
}

20
apps/docs/package.json
View File

@@ -25,25 +25,25 @@
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"fumadocs-core": "15.2.7",
"fumadocs-mdx": "11.6.0",
"fumadocs-mdx": "11.6.10",
"fumadocs-ui": "15.2.7",
"lucide-react": "^0.488.0",
"motion": "^12.9.1",
"next": "15.3.0",
"lucide-react": "^0.525.0",
"motion": "^12.23.0",
"next": "15.3.4",
"react": "^19.1.0",
"react-dom": "^19.1.0",
"tailwind-merge": "^3.2.0"
},
"devDependencies": {
"@tailwindcss/postcss": "^4.1.3",
"@tailwindcss/postcss": "^4.1.11",
"@types/mdx": "^2.0.13",
"@types/node": "22.14.0",
"@types/react": "^19.1.0",
"@types/react-dom": "^19.1.2",
"@types/react": "^19.1.8",
"@types/react-dom": "^19.1.6",
"eslint": "^8",
"eslint-config-next": "15.3.0",
"postcss": "^8.5.3",
"tailwindcss": "^4.1.3",
"eslint-config-next": "15.3.4",
"postcss": "^8.5.6",
"tailwindcss": "^4.1.11",
"tw-animate-css": "^1.2.8",
"typescript": "^5.8.3"
}

1512
apps/docs/pnpm-lock.yaml generated
View File

File diff suppressed because it is too large Load Diff

4
apps/docs/source.config.ts
View File

@@ -1,8 +1,8 @@
import { defineDocs, defineConfig } from 'fumadocs-mdx/config';
import { defineDocs, defineConfig } from "fumadocs-mdx/config";
// Options: https://fumadocs.vercel.app/docs/mdx/collections#define-docs
export const docs = defineDocs({
dir: 'content/docs',
dir: "content/docs",
});
export default defineConfig({

4
apps/docs/src/app/(home)/page.tsx
View File

@@ -59,7 +59,7 @@ const images = [
"https://res.cloudinary.com/technical-intelligence/image/upload/v1745546005/Palmr./profile_mizwvg.png",
];
const docsLink = "/docs/3.0-beta";
const docsLink = "/docs/3.1-beta";
export default function HomePage() {
return (
@@ -84,7 +84,7 @@ function Hero() {
<h1 className="mb-8 text-6xl font-bold">
Palmr.{" "}
<span className="text-[13px] font-light text-muted-foreground/50 font-mono">
v3.0-beta
v3.1-beta
</span>
</h1>
<h1 className="hidden text-4xl font-medium max-w-[600px] md:block mb-4">

6
apps/docs/src/app/api/search/route.ts
View File

@@ -8,10 +8,6 @@ export const { GET } = createFromSource(source, (page) => {
url: page.url,
id: page.url,
structuredData: page.data.structuredData,
tag: page.url.startsWith("/docs/3.0-beta")
? "v3.0-beta"
: page.url.startsWith("/docs/2.0.0-beta")
? "v2.0.0-beta"
: "v1.1.7-beta",
tag: page.url.startsWith("/docs/3.1-beta") ? "v3.1-beta" : "v2.0.0-beta",
};
});

10
apps/docs/src/app/docs/[[...slug]]/page.tsx
View File

@@ -5,7 +5,7 @@ import {
DocsDescription,
DocsTitle,
} from "fumadocs-ui/page";
import { notFound } from "next/navigation";
import { redirect } from "next/navigation";
import { createRelativeLink } from "fumadocs-ui/mdx";
import { getMDXComponents } from "@/mdx-components";
import { Footer } from "../components/footer";
@@ -17,14 +17,12 @@ export default async function Page(props: {
}) {
const params = await props.params;
const page = source.getPage(params.slug);
if (!page) notFound();
if (!page) redirect("/docs/3.1-beta");
const MDXContent = page.data.body;
// Check if this is an older version page that needs a warning
const shouldShowWarning =
page.url.startsWith("/docs/2.0.0-beta") ||
page.url.startsWith("/docs/1.1.7-beta");
const shouldShowWarning = page.url.startsWith("/docs/2.0.0-beta");
return (
<DocsPage
@@ -60,7 +58,7 @@ export async function generateMetadata(props: {
}) {
const params = await props.params;
const page = source.getPage(params.slug);
if (!page) notFound();
if (!page) redirect("/docs/3.1-beta");
return {
title: page.data.title + " | Palmr. Docs",

23
apps/docs/src/app/global.css
View File

@@ -165,6 +165,29 @@ h4 {
}
}
@layer utilities {
.line-clamp-1 {
overflow: hidden;
display: -webkit-box;
-webkit-box-orient: vertical;
-webkit-line-clamp: 1;
}
.line-clamp-2 {
overflow: hidden;
display: -webkit-box;
-webkit-box-orient: vertical;
-webkit-line-clamp: 2;
}
.line-clamp-3 {
overflow: hidden;
display: -webkit-box;
-webkit-box-orient: vertical;
-webkit-line-clamp: 3;
}
}
@theme inline {
--animate-pulse: pulse var(--duration) ease-out infinite;

8
apps/docs/src/app/layout.tsx
View File

@@ -28,19 +28,15 @@ export default function Layout({ children }: { children: ReactNode }) {
<RootProvider
search={{
options: {
defaultTag: "3.0-beta",
defaultTag: "3.1-beta",
tags: [
{
name: "v1.1.7 Beta",
value: "1.1.7-beta",
},
{
name: "v2.0.0 Beta",
value: "2.0.0-beta",
},
{
name: "v3.0 Beta ✨",
value: "3.0-beta",
value: "3.1-beta",
props: {
style: {
border: "1px solid rgba(0,165,80,0.2)",

85
apps/docs/src/components/OIDCProviderCards.tsx Normal file
View File

@@ -0,0 +1,85 @@
import { Card, CardGrid } from "@/components/ui/card";
import {
Chrome,
MessageSquare,
Github,
Shield,
Lock,
Key,
Users,
Settings,
Egg,
} from "lucide-react";
const providers = [
{
name: "Google",
description: "Configure authentication using Google OAuth2 services",
href: "/docs/3.1-beta/oidc-authentication/google",
icon: <Chrome className="w-4 h-4" />,
},
{
name: "Discord",
description: "Set up Discord OAuth2 for community-based authentication",
href: "/docs/3.1-beta/oidc-authentication/discord",
icon: <MessageSquare className="w-4 h-4" />,
},
{
name: "GitHub",
description: "Enable GitHub OAuth for developer-friendly sign-in",
href: "/docs/3.1-beta/oidc-authentication/github",
icon: <Github className="w-4 h-4" />,
},
{
name: "Zitadel",
description: "Enterprise-grade identity and access management",
href: "/docs/3.1-beta/oidc-authentication/zitadel",
icon: <Shield className="w-4 h-4" />,
},
{
name: "Auth0",
description: "Flexible identity platform with extensive customization",
href: "/docs/3.1-beta/oidc-authentication/auth0",
icon: <Lock className="w-4 h-4" />,
},
{
name: "Authentik",
description: "Open-source identity provider with modern features",
href: "/docs/3.1-beta/oidc-authentication/authentik",
icon: <Key className="w-4 h-4" />,
},
{
name: "Frontegg",
description: "User management platform for B2B applications",
href: "/docs/3.1-beta/oidc-authentication/frontegg",
icon: <Egg className="w-4 h-4" />,
},
{
name: "Kinde Auth",
description: "Developer-first authentication and user management",
href: "/docs/3.1-beta/oidc-authentication/kinde-auth",
icon: <Users className="w-4 h-" />,
},
{
name: "Other",
description: "Configure any other OIDC-compliant identity provider",
href: "/docs/3.1-beta/oidc-authentication/other",
icon: <Settings className="w-4 h-4" />,
},
];
export const OIDCProviderCards = () => {
return (
<CardGrid>
{providers.map((provider) => (
<Card
key={provider.name}
title={provider.name}
description={provider.description}
href={provider.href}
icon={provider.icon}
/>
))}
</CardGrid>
);
};

107
apps/docs/src/components/ui/card.tsx Normal file
View File

@@ -0,0 +1,107 @@
import Link from "next/link";
import { cn } from "@/lib/utils";
import { ReactNode } from "react";
interface CardProps {
title: string;
description: string;
href?: string;
icon?: ReactNode;
className?: string;
onClick?: () => void;
}
export const Card = ({
title,
description,
href,
icon,
className,
onClick,
}: CardProps) => {
const cardContent = (
<div
className={cn(
"group relative overflow-hidden rounded-xl border px-3 py-0 mt-0",
"bg-card text-card-foreground shadow-sm",
"hover:bg-accent/20 hover:border-accent-foreground/30 hover:shadow-md",
"transition-all duration-300 ease-out",
"focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
"cursor-pointer",
className
)}
>
<div className="flex items-center gap-3">
{icon && (
<div className="flex-shrink-0 -mt-11">
<div className="w-8 h-8 rounded-lg bg-gradient-to-br from-primary/15 to-primary/5 flex items-center justify-center group-hover:scale-105 transition-transform duration-200">
{icon}
</div>
</div>
)}
<div className="flex-1 min-w-0">
<h3 className="font-medium text-sm text-foreground mb-1 group-hover:text-primary transition-colors duration-200 mt-3 text-decoration-none">
{title}
</h3>
<p className="text-xs text-muted-foreground/80 leading-relaxed line-clamp-2 group-hover:text-muted-foreground transition-colors duration-200">
{description}
</p>
</div>
<div className="flex-shrink-0 ml-2">
<div className="w-5 h-5 rounded-full bg-muted/40 flex items-center justify-center opacity-0 group-hover:opacity-100 group-hover:bg-primary/10 transition-all duration-200">
<svg
className="w-3 h-3 text-muted-foreground group-hover:text-primary"
fill="none"
stroke="currentColor"
viewBox="0 0 24 24"
>
<path
strokeLinecap="round"
strokeLinejoin="round"
strokeWidth={2.5}
d="M9 5l7 7-7 7"
/>
</svg>
</div>
</div>
</div>
</div>
);
if (href) {
return (
<Link href={href} className="block no-underline">
{cardContent}
</Link>
);
}
if (onClick) {
return (
<button onClick={onClick} className="block w-full text-left">
{cardContent}
</button>
);
}
return cardContent;
};
interface CardGridProps {
children: ReactNode;
className?: string;
}
export const CardGrid = ({ children, className }: CardGridProps) => {
return (
<div
className={cn(
"grid grid-cols-1 sm:grid-cols-2 gap-2.5 mt-5",
"max-w-4xl",
className
)}
>
{children}
</div>
);
};

4
apps/docs/src/config/constants.ts
View File

@@ -1,2 +1,2 @@
export const LATEST_VERSION_PATH = "/docs/3.0-beta";
export const LATEST_VERSION = "v3.0-beta";
export const LATEST_VERSION_PATH = "/docs/3.1-beta";
export const LATEST_VERSION = "v3.1-beta";

5
apps/docs/src/mdx-components.tsx
View File

@@ -1,12 +1,17 @@
import defaultMdxComponents from "fumadocs-ui/mdx";
import type { MDXComponents } from "mdx/types";
import { KeyGenerator } from "@/components/KeyGenerator";
import { OIDCProviderCards } from "@/components/OIDCProviderCards";
import { Card, CardGrid } from "@/components/ui/card";
// use this function to get MDX components, you will need it for rendering MDX
export function getMDXComponents(components?: MDXComponents): MDXComponents {
return {
...defaultMdxComponents,
KeyGenerator,
OIDCProviderCards,
Card,
CardGrid,
...components,
};
}