mirror of
https://github.com/kyantech/Palmr.git
synced 2025-10-23 06:11:58 +00:00
docs: add API documentation and update meta.json for 1.1.7-beta and 2.0.0-beta
This commit introduces API documentation files for both 1.1.7-beta and 2.0.0-beta versions, including detailed guides on accessing and using Scalar and Swagger-based API documentation. Additionally, it updates the meta.json files for both versions to include the new API section and other relevant entries. The global.css file has also been updated to improve styling for code blocks and headings.
This commit is contained in:
Daniel Luiz Alves
50
apps/docs/content/docs/1.1.7-beta/api.md
Normal file
50
apps/docs/content/docs/1.1.7-beta/api.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
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:
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
|
||||
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)
|
||||
@@ -10,6 +10,7 @@
|
||||
"github-architecture",
|
||||
"installation",
|
||||
"manual-installation",
|
||||
"api",
|
||||
"---How to use Palmr.---",
|
||||
"login",
|
||||
"manage-users",
|
||||
|
||||
47
apps/docs/content/docs/2.0.0-beta/api.mdx
Normal file
47
apps/docs/content/docs/2.0.0-beta/api.mdx
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: 🔌 API Endpoints
|
||||
---
|
||||
|
||||
## 📚 Accessing the API Documentation
|
||||
|
||||
Palmr. provides a **comprehensive, well-documented, and fully typed API** that has been carefully designed to ensure maximum developer productivity and ease of integration.
|
||||
|
||||
### 🎯 Scalar-Based Documentation
|
||||
|
||||
This API can be accessed through dedicated documentation endpoints at:
|
||||
|
||||
- **In a production environment:** `{your_server_domain}/docs` or `{your_server_ip}/docs`
|
||||
- **In a local environment:** http://localhost:3333/docs
|
||||
|
||||
The API documentation is powered by **[Scalar](https://scalar.com/)**, which provides developers with a sophisticated and fully interactive interface for exploring, testing, and validating all available requests within the Palmr. ecosystem. This modern documentation platform enables real-time testing and visualization of API responses. Below is an example screenshot of the API documentation interface:
|
||||
|
||||
|
||||
|
||||
|
||||
We have made a deliberate decision to **not provide an online version** of the API documentation, as the endpoints and functionality may vary significantly depending on the specific version of Palmr. you have deployed in your environment. To ensure you're always working with accurate and version-specific documentation, we strongly recommend accessing the documentation only after initializing your API service. It's important to note that the API service is specifically designated as the **server** component within the official Palmr. GitHub repository.
|
||||
|
||||
We strongly recommend utilizing **Scalar** as your primary tool for querying and testing the API, as the entire documentation system has been carefully optimized and designed with Scalar integration in mind. Scalar provides developers with an exceptionally intuitive and feature-rich interactive environment that streamlines the process of exploring endpoints, constructing and sending requests, and analyzing responses directly within its sophisticated interface.
|
||||
|
||||
---
|
||||
|
||||
### 🔄 Swagger-Based Documentation
|
||||
|
||||
Understanding that developers may have different preferences or requirements, we also maintain a **Swagger-based version** of the documentation for those who prefer this widely-adopted documentation standard or require compatibility with existing tools and workflows.
|
||||
|
||||
|
||||
|
||||
This alternative documentation format can be accessed at the following endpoints:
|
||||
|
||||
- **In a production environment:** `{your_server_domain}/swagger` or `{your_server_ip}/swagger`
|
||||
- **In a local environment:** http://localhost:3333/swagger
|
||||
|
||||
Rest assured that both the Scalar and Swagger documentation versions maintain complete parity in terms of endpoint coverage and provide equally comprehensive documentation levels, ensuring successful testing and system integration regardless of your chosen documentation platform.
|
||||
|
||||
These carefully curated documentation options have been implemented to ensure that developers have access to all the necessary resources, detailed information, and interactive tools required for seamless integration between Palmr. and both internal systems and third-party services.
|
||||
|
||||
### 🔗 Useful Links
|
||||
|
||||
For additional information and detailed documentation about the tools that power our API documentation, please refer to these official resources:
|
||||
|
||||
- [Scalar Official Website](https://scalar.com/)
|
||||
- [Swagger Official Website](https://swagger.io/)
|
||||
108
apps/docs/content/docs/2.0.0-beta/first-login.mdx
Normal file
108
apps/docs/content/docs/2.0.0-beta/first-login.mdx
Normal file
@@ -0,0 +1,108 @@
|
||||
---
|
||||
title: 👋 First Login (Admin)
|
||||
---
|
||||
After successfully initiating all required services according to the detailed deployment instructions provided, you will gain access to the frontend interface through the following designated endpoints:
|
||||
|
||||
- **Production environment:** `{your_web_domain}` or `{your_server_ip}` - This is your primary access point for the live application deployment
|
||||
- **Local environment:** [http://localhost:4173](http://localhost:4173/) - This endpoint is specifically for development and testing purposes
|
||||
|
||||
Upon successfully navigating to the frontend interface through either of these endpoints, you will be presented with a comprehensive welcome screen, as illustrated in the image below:
|
||||
|
||||
|
||||
|
||||
What you are viewing is the **Palmr. landing page** ✨, which serves as an introductory interface providing essential information about the application's capabilities and features. While this landing page is displayed by default during your initial setup, you have the flexibility to modify this configuration later. Should you prefer, you can configure the system to bypass this landing page and present the login interface as your primary entry point. However, for the purposes of initial system familiarization, the landing page is deliberately set as the default welcome screen.
|
||||
|
||||
---
|
||||
|
||||
## 🔑 First Login
|
||||
|
||||
Prominently displayed at the top of the landing page, you will notice a clearly marked button that enables you to authenticate and access Palmr.:
|
||||
|
||||
> But you may wonder:
|
||||
>
|
||||
|
||||
To facilitate a smooth onboarding experience, Palmr. has been thoughtfully designed with pre-configured **seed data** that is automatically implemented during the initial system initialization. This preliminary data setup includes a comprehensive **admin user** account that is granted complete access privileges, enabling full control over all system settings and user management functionalities within the application environment.
|
||||
|
||||
Upon selecting the **Login** button, the system will seamlessly redirect you to the authentication interface, which presents itself as shown in the following image:
|
||||
|
||||
|
||||
|
||||
For your initial access to the system, please utilize these pre-configured authentication credentials:
|
||||
|
||||
### 👤 Admin Credentials
|
||||
|
||||
| User | Password |
|
||||
| --- | --- |
|
||||
| `admin@example.com` | `admin123` |
|
||||
|
||||
Following successful validation of your credentials, the system will authenticate your session and automatically direct you to Palmr.'s primary dashboard interface, which appears as demonstrated in this image:
|
||||
|
||||
|
||||
|
||||
Having completed these steps successfully, you have now established an authenticated session and are fully prepared to explore and utilize the comprehensive feature set that Palmr. has to offer! 🎉
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Recommendations After First Access
|
||||
|
||||
Given that Palmr.'s initial configuration includes a solitary default admin user within the seed data, it is **strongly recommended** as a security best practice to modify the default administrative credentials immediately following your first successful login. This crucial step is fundamental to establishing and maintaining the security integrity of your Palmr. instance.
|
||||
|
||||
Please follow this detailed sequence of steps to update your administrative credentials and enhance the security of your Palmr. installation:
|
||||
|
||||
### 🔧 Access the Profile Settings
|
||||
|
||||
1. Locate and click the **user icon** positioned in the upper right corner of your screen interface.
|
||||
2. Upon clicking, you will be presented with an expandable dropdown menu containing several configuration options:
|
||||
|
||||
|
||||
|
||||
1. From the available options in the dropdown menu, select **"Profile"**. This selection will navigate you to the comprehensive profile settings interface:
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
### 📝 Update the Admin Profile
|
||||
|
||||
Within the profile settings interface, you have full access to modify all information associated with the administrative account.
|
||||
|
||||
- To enhance security through password modification, input and confirm your newly chosen secure password.
|
||||
- Take this opportunity to review and adjust any additional profile details according to your specific requirements and preferences.
|
||||
|
||||
**Tip:** ✨ To establish robust security measures, ensure your new password incorporates the following elements:
|
||||
|
||||
- A minimum length of 12 characters to provide adequate complexity
|
||||
- A diverse combination of uppercase and lowercase alphabetical characters
|
||||
- An assortment of numerical digits and special character symbols
|
||||
|
||||
---
|
||||
|
||||
### 📸 Update the Profile Picture
|
||||
|
||||
To enhance the personalization of your administrative profile, you have the option to customize your profile picture.
|
||||
|
||||
1. Identify and select the **camera icon** positioned adjacent to your current avatar display.
|
||||
2. Browse and select an appropriate image file from your local storage device.
|
||||
|
||||
|
||||
|
||||
> 💡 Recommendation: For optimal visual presentation, utilize an image with equal width and height dimensions (square format).
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Troubleshooting
|
||||
|
||||
Should you encounter any technical difficulties during the initial authentication process or while updating your profile information, please verify the following system components:
|
||||
|
||||
- Confirm the operational status of all essential services, including the frontend interface, backend systems, MinIO storage, and database connections.
|
||||
- Verify the accurate configuration of all necessary environment variables within your system.
|
||||
- Ensure the successful and complete application of all database seed operations.
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security Best Practices
|
||||
|
||||
- Following the successful configuration of your administrative account, establish additional user accounts with appropriately restricted access permissions based on specific roles and responsibilities.
|
||||
- Implement HTTPS protocol to ensure secure data transmission between client devices and the server infrastructure.
|
||||
- Maintain system security by regularly implementing updates to your Palmr. installation to incorporate the latest security patches and system improvements.
|
||||
81
apps/docs/content/docs/2.0.0-beta/manage-users.mdx
Normal file
81
apps/docs/content/docs/2.0.0-beta/manage-users.mdx
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: 👥 Users Management
|
||||
---
|
||||
|
||||
Managing users in **Palmr.** is a straightforward and intuitive process that ensures proper access control and organization within your system. This comprehensive step-by-step guide will walk you through the essential processes of creating, modifying, and managing user accounts within the application.
|
||||
|
||||
## 🔐 Accessing User Management
|
||||
|
||||
To initiate the user management process, you'll need to navigate to the dedicated **User Management** section. This centralized hub provides all the tools necessary for effective user administration:
|
||||
|
||||
1. Locate and click on the **user icon** prominently displayed in the application's header area, where all primary navigation controls are situated.
|
||||
2. Upon clicking, a comprehensive dropdown menu will appear, presenting various options. From these choices, locate and select **"User Management"** to proceed
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
### 📊 User Management Dashboard
|
||||
|
||||
Upon selecting **User Management**, the system will automatically direct you to the comprehensive **User Management Dashboard**, your central control panel for all user-related operations.
|
||||
|
||||
- During your initial access to the system, you'll notice that the user list contains only the **default Admin** user account, which serves as the primary administrative account.
|
||||
- Should you find it necessary to modify the Admin user's information or credentials, please note that these changes must be implemented through the dedicated **Profile Management** section, which provides specialized tools for administrator profile maintenance.
|
||||
- For security purposes and to maintain system integrity, it's important to understand that the currently logged-in Admin user's details cannot be altered directly from within the **User Management Dashboard**.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
### 👤 Adding a New User
|
||||
|
||||
1. To initiate the process of adding a new user to the system, locate and click the **"Add User"** button, which is conveniently positioned in the top right corner of your screen for easy access.
|
||||
|
||||
|
||||
|
||||
1. Upon clicking, an interactive modal form will be displayed, presenting you with all the necessary fields to input the new user's comprehensive details and access permissions:
|
||||
|
||||
|
||||
|
||||
1. After carefully entering all the required user information and reviewing for accuracy, click the **"Create"** button to finalize the process. ✨ If you need to start over or decide not to proceed, simply click the **"Cancel"** button to terminate the user creation process without saving any changes.
|
||||
2. Following successful user creation, the new account will be immediately visible in the user list, confirming the completion of the process. 🎉
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
### ⚙️ Managing User Actions
|
||||
|
||||
Within the **User List** interface, you'll find a comprehensive **"Actions"** column containing a dropdown menu for each user account, providing access to all available management functions.
|
||||
|
||||
|
||||
|
||||
The following administrative actions are available for your convenience:
|
||||
|
||||
- 📝 **Edit User** – Provides access to a detailed modal form for comprehensive user information updates:
|
||||
- Modify various user details including their assigned role and permissions within the system.
|
||||
- Implement security measures such as password changes and access control modifications.
|
||||
|
||||
|
||||
|
||||
- 🔒 **Deactivate User** – Temporarily suspends user access by marking the account as inactive, effectively preventing any system login attempts while maintaining their account information.
|
||||
- 🔓 **Activate User** – Restores full system access for previously deactivated users, enabling them to resume normal account activities and authentication.
|
||||
- ❌ **Delete User** – Executes a permanent removal of the user account from the system, including all associated data and permissions.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Troubleshooting
|
||||
|
||||
In the event of any challenges or issues during the user management process, please refer to the following troubleshooting guidelines:
|
||||
|
||||
### 🚫 User Creation Fails
|
||||
|
||||
- Carefully verify that all required fields (including name, email address, and role assignments) have been completed with accurate information.
|
||||
- Perform a thorough check to ensure the email address isn't already associated with an existing account in the system.
|
||||
- Confirm that your system maintains a stable and active connection to the backend services necessary for user management.
|
||||
|
||||
### 🔑 User Cannot Log In
|
||||
|
||||
- First, verify that the user's account status is set to **Active** in the system.
|
||||
- Double-check that the user is attempting to authenticate with their correct email address and current password combination.
|
||||
- If authentication issues persist, initiate a password reset procedure to establish new credentials.
|
||||
212
apps/docs/content/docs/2.0.0-beta/manual-installation.mdx
Normal file
212
apps/docs/content/docs/2.0.0-beta/manual-installation.mdx
Normal file
@@ -0,0 +1,212 @@
|
||||
---
|
||||
title: 📦 Manual Installation
|
||||
---
|
||||
|
||||
Manual installation requires more detailed attention and hands-on configuration compared to the streamlined process offered by Docker Compose. While this approach demands additional effort and technical understanding, following our comprehensive step-by-step guide will ensure a clean and successful project execution with full control over each component.
|
||||
|
||||
An important consideration in this manual setup process is that while we'll be handling the frontend and backend deployments directly, we still require Docker or an equivalent third-party service to manage our Postgres database and MinIO object storage infrastructure. For the purposes of this tutorial, we've chosen to utilize Docker with Docker Compose to establish and configure both MinIO and Postgres, as this provides a reliable and well-tested environment.
|
||||
|
||||
To facilitate this setup, we've included a pre-configured Docker Compose file within the `apps/server` directory that handles the initialization and configuration of both MinIO and Postgres - two essential components for the application's core functionality. While this is our recommended approach, you maintain the flexibility to implement alternative solutions that better suit your specific needs or infrastructure requirements. Our decision to leverage Docker Compose for these particular services stems from its ability to significantly streamline the configuration process, especially when dealing with complex third-party services like Postgres and MinIO.
|
||||
|
||||
Should you be interested in exploring alternative deployment methods for hosting MinIO and Postgres without utilizing Docker and Docker Compose, comprehensive information is available through their respective official channels and documentation:
|
||||
|
||||
- MinIO GitHub: [Visit MinIO GitHub](https://github.com/minio/minio)
|
||||
- Postgres Github: [Visit Postgres GitHub](https://github.com/postgres/postgres)
|
||||
- MinIO documentation: [View MinIO docs](https://min.io/docs/minio/linux/index.html)
|
||||
- Postgres documentation: [View Postgres docs](https://www.postgresql.org/docs/)
|
||||
|
||||
With these foundational concepts established, we can now proceed with our detailed, step-by-step installation guide.
|
||||
|
||||
---
|
||||
|
||||
## ✅ Prerequisites
|
||||
|
||||
Before proceeding with the installation, it's essential to ensure that your development environment is properly configured with all the necessary tools and dependencies. Please verify that you have the following software components installed and properly configured on your system:
|
||||
|
||||
- <span style={{ color: "#16a34a" }}>Docker</span> *(Required only if you plan to use Docker + Docker Compose)*
|
||||
- <span style={{ color: "#16a34a" }}>Docker Compose</span> *(Required only if you plan to use Docker + Docker Compose)*
|
||||
- <span style={{ color: "#16a34a" }}>Node.js</span> *(Essential for running JavaScript/TypeScript applications)*
|
||||
- <span style={{ color: "#16a34a" }}>pnpm</span> *(Our preferred package manager)*
|
||||
- <span style={{ color: "#16a34a" }}>Git</span> *(For version control and repository management)*
|
||||
|
||||
⚠️ <strong>A critical note regarding package management:</strong> This repository has been specifically developed and thoroughly tested using the pnpm package manager. While technically possible to use alternative package managers such as `npm`, `yarn`, or `bun`, we strongly advise against this approach.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Running the Application
|
||||
|
||||
### 📥 Clone the Repository
|
||||
|
||||
To begin the installation process, you'll need to obtain a local copy of the codebase. Start by cloning the official repository using the following Git command:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/kyantech/Palmr.git
|
||||
```
|
||||
|
||||
Upon successful cloning, you'll find yourself with a new directory containing the project structure. Within this directory, there's a crucial folder named 'apps' that houses three essential components: docs, server, and web. For the purposes of this installation guide, we'll focus primarily on the server and web directories, which contain our robust backend infrastructure (built with Fastify) and our responsive frontend application (developed using React + Vite), respectively.
|
||||
|
||||
---
|
||||
|
||||
### ⚙️ Set Up Backend Services
|
||||
|
||||
The next phase involves setting up our backend services. First, navigate to the backend directory where you'll find the Docker Compose configuration file for our essential services - MinIO and Postgres:
|
||||
|
||||
```bash
|
||||
cd ./apps/server
|
||||
```
|
||||
|
||||
Once you're in the correct directory, initiate the services by executing the following command:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
This command initializes both Postgres and MinIO services in detached mode, allowing them to run seamlessly in the background. While the configuration file at `apps/server/docker-compose.yaml` can be customized to suit specific needs, we strongly recommend maintaining the default configuration for your initial setup. This approach ensures a smooth installation process, and you can always refine the settings once you have a working implementation.
|
||||
|
||||
Now that our essential services are operational through Docker Compose, we can proceed with the core backend setup. During this phase, we'll be preparing the application for production deployment rather than development mode. This process requires careful attention to both the backend and frontend components.
|
||||
|
||||
Since our current working directory is already set to the server folder, let's begin with the backend configuration.
|
||||
|
||||
#### 🔑 Set Up Environment Variables
|
||||
|
||||
A crucial preliminary step is configuring the environment variables that Palmr requires for proper operation. We've provided a template file named `.env.example` in the repository to streamline this process.
|
||||
|
||||
Execute this straightforward command to create your environment configuration:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
This operation creates a new `.env` file in the root directory, populated with all the necessary environmental configurations.
|
||||
|
||||
#### 📦 Install Dependencies
|
||||
|
||||
The next crucial step involves initializing our database connection through Prisma, our chosen Object-Relational Mapping (ORM) tool. However, before we can utilize Prisma effectively, we need to ensure all backend dependencies are properly installed. With your Node.js environment and pnpm package manager ready, execute:
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
#### ⚡ Generate Prisma Client
|
||||
|
||||
After successfully installing all dependencies, proceed with generating the Prisma client by running:
|
||||
|
||||
```bash
|
||||
pnpm dlx prisma generate
|
||||
```
|
||||
|
||||
This essential command generates the Prisma client specifically tailored for our project, establishing the necessary interface for seamless database interactions and operations.
|
||||
|
||||
#### 🔄 Deploy Prisma Migrations
|
||||
|
||||
With the client generation complete, deploy the database schema using:
|
||||
|
||||
```bash
|
||||
pnpm dlx prisma migrate deploy
|
||||
```
|
||||
|
||||
This command ensures all your database migrations are properly implemented, establishing the required database structure.
|
||||
|
||||
#### 🌱 Seed the Database
|
||||
|
||||
Following the successful migration deployment, we'll populate the database with initial data using our seeding script. Execute:
|
||||
|
||||
```bash
|
||||
pnpm db:seed
|
||||
```
|
||||
|
||||
This process will populate your database with the necessary initial data, preparing it for application use.
|
||||
|
||||
#### 🏗️ Build and Run the Backend
|
||||
|
||||
With all preparatory steps completed, we can now build the backend application:
|
||||
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
Once the build process successfully concludes, start the backend service:
|
||||
|
||||
```bash
|
||||
pnpm start
|
||||
```
|
||||
|
||||
To verify that your backend is functioning correctly, you can access the comprehensive API documentation at:
|
||||
|
||||
```bash
|
||||
http://localhost:3333/docs
|
||||
```
|
||||
|
||||
This documentation interface provides detailed information about all available API endpoints and their usage.
|
||||
|
||||
---
|
||||
|
||||
### 🎨 Set Up Frontend
|
||||
|
||||
The frontend configuration process follows a similar pattern to the backend setup, though it's somewhat simplified as it doesn't require Docker container management - we'll only need to configure and run the service itself.
|
||||
|
||||
#### 📂 Navigate to the Frontend Directory
|
||||
|
||||
If your current location is the server directory, use:
|
||||
|
||||
```bash
|
||||
cd ../web
|
||||
```
|
||||
|
||||
Alternatively, if you're starting from the repository root, navigate with:
|
||||
|
||||
```bash
|
||||
cd apps/web
|
||||
```
|
||||
|
||||
#### ⚙️ Set Up Environment Variables
|
||||
|
||||
After reaching the web directory, begin by creating your frontend environment configuration:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
This step mirrors our backend environment setup, ensuring all necessary variables are properly configured.
|
||||
|
||||
#### 📦 Install Dependencies
|
||||
|
||||
Proceed with installing all required frontend dependencies:
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
#### 💻 Build and Run the Frontend
|
||||
|
||||
The final stage of our frontend setup is straightforward. First, create a production build:
|
||||
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
After the build completes successfully, launch the frontend service:
|
||||
|
||||
```bash
|
||||
pnpm serve
|
||||
```
|
||||
|
||||
Once the service initialization is complete, you can access the full application through your web browser at:
|
||||
|
||||
```bash
|
||||
http://localhost:3000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Conclusion
|
||||
|
||||
Congratulations! You've successfully completed the comprehensive setup process for deploying a production-ready instance of Palmr. This detailed guide has walked you through each crucial step, from initial repository cloning to final application deployment.
|
||||
|
||||
## 🔗 Useful Links
|
||||
|
||||
- [Docker Documentation](https://docs.docker.com/)
|
||||
- [Node.js Documentation](https://nodejs.org/en/docs/)
|
||||
- [pnpm Documentation](https://pnpm.io/)
|
||||
- [Prisma Documentation](https://www.prisma.io/docs/)
|
||||
@@ -9,7 +9,12 @@
|
||||
"architecture",
|
||||
"github-architecture",
|
||||
"installation",
|
||||
"manual-installation",
|
||||
"api",
|
||||
"---How to use Palmr.---",
|
||||
"first-login",
|
||||
"manage-users",
|
||||
"uploading-files",
|
||||
"..."
|
||||
]
|
||||
}
|
||||
|
||||
91
apps/docs/content/docs/2.0.0-beta/uploading-files.mdx
Normal file
91
apps/docs/content/docs/2.0.0-beta/uploading-files.mdx
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
title: 📤 Uploading Files
|
||||
---
|
||||
|
||||
To upload a file in Palmr, the process has been designed to be straightforward and user-friendly. The platform offers two convenient locations where users can upload their files, ensuring flexibility and ease of access. Each location has been optimized to provide a seamless upload experience.
|
||||
|
||||
Before we delve into the specifics of file uploading, it's essential to understand that file sharing stands at the heart of Palmr's functionality. This core feature enables users to collaborate and distribute content efficiently. To initiate this collaborative process, you'll need to first upload one or more files to your account. Once your files are uploaded, you can proceed to create a sharing session, which serves as a container that can encompass either a single file or multiple files, depending on your specific needs.
|
||||
|
||||
Now let's explore the file upload process in detail. As previously mentioned, the procedure has been streamlined for maximum efficiency, and you can initiate file uploads from two distinct locations: **the Home Page** or **the My Files Page**. We will thoroughly examine both options in the following sections, though it's worth noting that the underlying upload mechanism remains consistent regardless of which location you choose.
|
||||
|
||||
---
|
||||
|
||||
## 🏠 Home Page
|
||||
|
||||
On the home page, you'll find a dedicated "Recent Uploads" section. When you're using Palmr for the first time and haven't uploaded any files yet, this section will appear in its initial state:
|
||||
|
||||
|
||||
|
||||
To begin the upload process, locate and click the "Upload File" button. This action will trigger a modal window where you can browse and select the desired file from your device. For enhanced user experience, certain file formats including images, audio files, and video content will automatically generate a preview within the modal.
|
||||
|
||||
|
||||
|
||||
|
||||
**Example with an image:**
|
||||
|
||||
|
||||
|
||||
Upon selecting your file, you'll be presented with two options: confirm the upload by clicking the "Upload" button, or if you need to make changes, you can abort the process by selecting the "Cancel" button.
|
||||
|
||||
|
||||
|
||||
After successfully uploading one or more files, the "Recent Uploads" section will automatically refresh to display your newly added content:
|
||||
|
||||
|
||||
|
||||
Should you wish to upload additional files from this view, simply click the "Upload File" button positioned in the upper right corner of the section, then follow the same straightforward procedure outlined above.
|
||||
|
||||
|
||||
|
||||
It's important to note that the home page list displays only your last 5 uploads for quick access. For a comprehensive view of your uploaded files or to upload additional content, you'll need to navigate to the "My Files" page. This can be accomplished in two ways: either click the "View All" button located in the upper right corner of the section, or select the "My Files" card directly from the home page.
|
||||
|
||||
|
||||
|
||||
Or:
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📂 My Files Page
|
||||
|
||||
Upon accessing the **"My Files"** page, you'll be presented with this comprehensive layout:
|
||||
|
||||
This interface provides enhanced functionality, allowing you to **filter** through your uploaded files for better organization. You can also continue uploading new files by clicking the **"Upload File"** button and following the previously described upload procedure.
|
||||
|
||||
For clarity, it's worth mentioning that the tables found in both the **"Recent Files"** section and the **"My Files"** page share the same structure and organization — the primary distinction lies in the quantity of files displayed. While the **"Recent Files"** section provides quick access to your five most recent uploads, the **"My Files"** table presents a comprehensive view of your entire upload history.
|
||||
|
||||
The table provides detailed information through the following fields:
|
||||
|
||||
- **Name**
|
||||
- **Description**
|
||||
- **Size**
|
||||
- **Created At**
|
||||
- **Updated At**
|
||||
- **Actions**
|
||||
|
||||
---
|
||||
|
||||
### ⚙️ Actions Column
|
||||
|
||||
Within the **"Actions"** column, you'll discover an interactive icon that reveals the following dropdown menu:
|
||||
|
||||
|
||||
|
||||
While most options are self-explanatory, let's examine the Edit functionality in detail:
|
||||
|
||||
- Edit – Opens a modal where you can modify various file attributes including the file name, description, and other relevant details.
|
||||
|
||||
|
||||
|
||||
- The platform also provides the ability to **delete** files directly through the dropdown menu by selecting the **Delete** option.
|
||||
|
||||
For enhanced user experience, the preview functionality is available for common media formats including images, audio files, PDFs, and videos. For all other file types, you can easily access the content through the **Download** option in the dropdown menu.
|
||||
|
||||
---
|
||||
|
||||
## 📝 Notes and Recommendations
|
||||
|
||||
- To ensure optimal performance and user experience, we strongly recommend uploading files that have been properly optimized.
|
||||
- For troubleshooting purposes, all upload errors and related issues are systematically logged and can be accessed through the administrative panel.
|
||||
- System administrators have full control over file access permissions and can manage them as needed.
|
||||
BIN
apps/docs/public/assets/v2/api-docs/scalar.png
Normal file
BIN
apps/docs/public/assets/v2/api-docs/scalar.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 222 KiB |
BIN
apps/docs/public/assets/v2/api-docs/swagger.png
Normal file
BIN
apps/docs/public/assets/v2/api-docs/swagger.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 182 KiB |
@@ -1,6 +1,20 @@
|
||||
@import 'tailwindcss';
|
||||
@import 'fumadocs-ui/css/neutral.css';
|
||||
@import 'fumadocs-ui/css/preset.css';
|
||||
@import "tailwindcss";
|
||||
@import "fumadocs-ui/css/neutral.css";
|
||||
@import "fumadocs-ui/css/preset.css";
|
||||
/* @import 'fumadocs-ui/css/black.css'; */
|
||||
|
||||
@source '../../node_modules/fumadocs-ui/dist/**/*.js';
|
||||
|
||||
code {
|
||||
color: #eb5757;
|
||||
}
|
||||
|
||||
h4 {
|
||||
margin-bottom: 1rem;
|
||||
margin-top: 3rem;
|
||||
font-size: 1.1rem;
|
||||
}
|
||||
|
||||
.prose h3 {
|
||||
font-size: 1.25rem;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user