mirror of
https://github.com/unraid/api.git
synced 2026-01-08 17:49:59 -06:00
7aa55883e2
<!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Chores** - Refined repository settings to auto-exclude environment and build-related files. - Introduced a new configuration that streamlines local development and displays key tool versions on setup. - **Documentation** - Expanded contribution guidelines with a dedicated developer resources section linking to guides on development practices and repository structure. - Updated workflow instructions to better assist developers in setting up their environment, especially for those using Nix. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
220 lines
3.5 KiB
Markdown
220 lines
3.5 KiB
Markdown
# Unraid API Development Workflows
|
|
|
|
This document outlines the various workflow styles available for developing, building, and deploying the Unraid API monorepo.
|
|
|
|
## Repository Structure
|
|
|
|
The Unraid API monorepo consists of several packages:
|
|
|
|
- `api`: The Unraid API backend
|
|
- `web`: The web frontend components
|
|
- `plugin`: The Unraid plugin
|
|
- `unraid-ui`: UI components library
|
|
|
|
## Development Workflows
|
|
|
|
### Local Development
|
|
|
|
To start all development servers in the monorepo:
|
|
|
|
```bash
|
|
pnpm dev
|
|
```
|
|
|
|
This command runs all development servers concurrently:
|
|
|
|
- API server: <http://localhost:3001>
|
|
- Web components: <http://localhost:4321>
|
|
- UI components: <http://localhost:5173>
|
|
|
|
### Package-Specific Development
|
|
|
|
If you want to work on a specific package, you can run its development server individually:
|
|
|
|
#### API Development
|
|
|
|
```bash
|
|
cd api
|
|
pnpm dev
|
|
```
|
|
|
|
#### Web Development
|
|
|
|
```bash
|
|
cd web
|
|
pnpm dev
|
|
```
|
|
|
|
#### UI Component Development
|
|
|
|
```bash
|
|
cd unraid-ui
|
|
pnpm dev
|
|
```
|
|
|
|
## Building Workflows
|
|
|
|
### Building All Packages
|
|
|
|
To build all packages in the monorepo:
|
|
|
|
```bash
|
|
pnpm build
|
|
```
|
|
|
|
### Watch Mode Building
|
|
|
|
For continuous building during development:
|
|
|
|
```bash
|
|
pnpm build:watch
|
|
```
|
|
|
|
This is useful when you want to see your changes reflected without manually rebuilding. This will also allow you to install a local plugin to test your changes.
|
|
|
|
### Package-Specific Building
|
|
|
|
#### API Building
|
|
|
|
```bash
|
|
cd api
|
|
pnpm build
|
|
```
|
|
|
|
#### Web Building
|
|
|
|
```bash
|
|
cd web
|
|
pnpm build
|
|
```
|
|
|
|
#### Development Build for Web
|
|
|
|
```bash
|
|
cd web
|
|
pnpm build:dev
|
|
```
|
|
|
|
## Deployment Workflows
|
|
|
|
### Deploying to Development Unraid Server
|
|
|
|
To deploy to a development Unraid server:
|
|
|
|
```bash
|
|
pnpm unraid:deploy <SERVER_IP>
|
|
```
|
|
|
|
This command builds and deploys all components to the specified Unraid server.
|
|
|
|
### Package-Specific Deployment
|
|
|
|
#### API Deployment
|
|
|
|
```bash
|
|
cd api
|
|
pnpm unraid:deploy <SERVER_IP>
|
|
```
|
|
|
|
#### Web Deployment
|
|
|
|
```bash
|
|
cd web
|
|
pnpm unraid:deploy <SERVER_IP>
|
|
```
|
|
|
|
#### Plugin Deployment
|
|
|
|
```bash
|
|
cd plugin
|
|
pnpm unraid:deploy <SERVER_IP>
|
|
```
|
|
|
|
## Testing
|
|
|
|
To run tests across all packages:
|
|
|
|
```bash
|
|
pnpm test
|
|
```
|
|
|
|
### Package-Specific Testing
|
|
|
|
```bash
|
|
cd <package-directory>
|
|
pnpm test
|
|
```
|
|
|
|
## Code Quality Workflows
|
|
|
|
### Linting
|
|
|
|
To lint all packages:
|
|
|
|
```bash
|
|
pnpm lint
|
|
```
|
|
|
|
To automatically fix linting issues:
|
|
|
|
```bash
|
|
pnpm lint:fix
|
|
```
|
|
|
|
### Type Checking
|
|
|
|
To run type checking across all packages:
|
|
|
|
```bash
|
|
pnpm type-check
|
|
```
|
|
|
|
## GraphQL Codegen Workflows
|
|
|
|
For packages that use GraphQL, you can generate types from your schema:
|
|
|
|
```bash
|
|
cd <package-directory>
|
|
pnpm codegen
|
|
```
|
|
|
|
To watch for changes and regenerate types:
|
|
|
|
```bash
|
|
cd <package-directory>
|
|
pnpm codegen:watch
|
|
```
|
|
|
|
## Docker Workflows
|
|
|
|
The API package supports Docker-based development:
|
|
|
|
```bash
|
|
cd api
|
|
pnpm container:build # Build the Docker container
|
|
pnpm container:start # Start the container
|
|
pnpm container:stop # Stop the container
|
|
pnpm container:enter # Enter the container shell
|
|
pnpm container:test # Run tests in the container
|
|
```
|
|
|
|
## CLI Commands
|
|
|
|
When working with a deployed Unraid API, you can use the CLI:
|
|
|
|
```bash
|
|
unraid-api --help
|
|
```
|
|
|
|
## Recommended Workflow for New Developers
|
|
|
|
1. Clone the repository: `git clone git@github.com:unraid/api.git`
|
|
2. Set up the monorepo: `just setup` or `pnpm install`
|
|
3. Start development servers: `pnpm dev`
|
|
4. Make your changes
|
|
5. Test your changes: `pnpm test`
|
|
6. Deploy to a development server: `pnpm unraid:deploy <SERVER_IP>`
|
|
7. Verify your changes on the Unraid server
|
|
|
|
If using nix, run `nix develop` from the root of the repo before Step 2.
|