tronnet/ProxmoxAAS-API
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update README

Browse Source
This commit is contained in:
Arthur Lu 2024-01-16 22:36:21 +00:00
parent fae2eb1724
commit 1a8e804be1
1 changed files with 27 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
README.md
View File

@ -1,14 +1,16 @@
# ProxmoxAAS API - REST API for ProxmoxAAS Dashboard # ProxmoxAAS API - REST API for ProxmoxAAS Dashboard
ProxmoxAAS API provides functionality for the Dashboard by providing a proxy API for the Proxmox API, and an API for requesting resources within a defined quota. ProxmoxAAS API provides functionality for the Dashboard by providing a proxy API for the Proxmox API, and an API for requesting resources within a defined quota.
## Prerequisites ## Installation
### Prerequisites
- [ProxmoxAAS-Dashboard](https://git.tronnet.net/tronnet/ProxmoxAAS-Dashboard) - [ProxmoxAAS-Dashboard](https://git.tronnet.net/tronnet/ProxmoxAAS-Dashboard)
- Proxmox VE Cluster (v7.0+) - Proxmox VE Cluster (v7.0+)
- Reverse proxy server which can proxy the dashboard and API - Reverse proxy server which can proxy the dashboard and API
- FQDN - FQDN
- Server with NodeJS (v18.0+) and NPM installed - Server with NodeJS (v18.0+) and NPM installed
## Configuring API Token and Permissions ### Configuring API Token and Permissions
In Proxmox VE, follow the following steps: In Proxmox VE, follow the following steps:
1. Add a new user `proxmoxaas-api` to Proxmox VE 1. Add a new user `proxmoxaas-api` to Proxmox VE
2. Create a new API token for the user `proxmoxaas-api` and copy the secret key to a safe location 2. Create a new API token for the user `proxmoxaas-api` and copy the secret key to a safe location
@ -20,22 +22,28 @@ In Proxmox VE, follow the following steps:
4. Add a new API Token Permission with path: `/`, select the API token created previously, and role: `proxmoxaas-api` 4. Add a new API Token Permission with path: `/`, select the API token created previously, and role: `proxmoxaas-api`
5. Add a new User Permission with path: `/`, select the `proxmoxaas-api` user, and role: `proxmoxaas-api` 5. Add a new User Permission with path: `/`, select the `proxmoxaas-api` user, and role: `proxmoxaas-api`
## Installation - API ### Installation - API
1. Clone this repo onto `Dashboard Host` 1. Clone this repo onto `Dashboard Host`
2. Run `npm install` to initiaze the package requirements 2. Run `npm install` to initiaze the package requirements
3. Copy `template.localdb.json` as `localdb.json` and modify the following values under `pveAPIToken`: 3. Copy `template.config.json` as `config.json` and modify the following values:
- pveAPI - the URI to the Proxmox API, ie `<proxmoxhost>:8006/api2/json` or `<proxmox URL>/api2/json` if Proxmox VE is behind a reverse proxy. 1. In `backends/pve/config`:
- hostname - the ProxmoxAAS-Dashboard URL, ie `host.domain.tld` - url: the URI to the Proxmox API, ie `http://<proxmoxhost>:8006/api2/json` or `http://<proxmox URL>/api2/json` if Proxmox VE is behind a reverse proxy.
- domain - the base domain for the dashboard and proxmox, ie `domain.tld` - token: the user(name), authentication realm (pam), token id, and token secrey key (uuid)
- listenPort - the port you want the API to listen on, ie `8080` - root (**Optional**): In order to allow users to customize instance pcie devices, the API must use the root credentials for privilege elevation. Provide the root username, ie. `root@pam`, and root user password
- pveAPIToken - the user(name), authentication realm, token id, and token secrey key (uuid) 2. In `backends/paasldap/config` (**Optional**):
4. (Optional) In order to allow users to customize instance pcie devices, the API must use the root credentials for privilege elevation. Modify the following values under `pveroot` in order to use this feature: - url: url to a PAAS-LDAP server API ie. `http://<paasldap-host>:8082`
- username: root user name, typically `root@pam` 3. In `handlers/auth`:
- password: root user password - Add any authentication handlers to be used by the API. Add the realm name (ie. `pve`) as the key and the handler name as provided in `backends`. For example, a PAAS-LDAP handler could be added as `"paas-ldap": "paasldap"` and users in the realm `user@paas-ldap` will use this handler to perform auth actions. Refer to [backends](#Backends)
5. You may also wish to configure users at this point as well. An example user config is shown in the template. 4. In `application`:
6. Start the service using `node .`, or call the provided shell script, or use the provided systemctl service script - hostname - the ProxmoxAAS-Dashboard URL, ie `host.domain.tld`
- domain - the base domain for the dashboard and proxmox, ie `domain.tld`
- listenPort - the port you want the API to listen on, ie `8081`
5. In `useriso`:
- node: host of storage with user accessible iso files
- storage: name of storage with user accessible iso files
4. Start the service using `node .`, or call the provided shell script, or use the provided systemctl service script
## Installation - Reverse Proxy ### Installation - Reverse Proxy
1. Configure nginx or preferred reverse proxy to reverse proxy the dashboard. The configuration should include at least the following: 1. Configure nginx or preferred reverse proxy to reverse proxy the dashboard. The configuration should include at least the following:
``` ```
server { server {
@ -56,5 +64,7 @@ server {
``` ```
2. Start nginx with the new configurations 2. Start nginx with the new configurations
## Result ### Result
After these steps, the ProxmoxAAS Dashboard should be available and fully functional at `paas.<FQDN>` or `paas.<FQDN>/dashboard/`. After these steps, the ProxmoxAAS Dashboard should be available and fully functional at `paas.<FQDN>` or `paas.<FQDN>/dashboard/`.
# Backends