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 c9e4bb7484
commit 0013833bce
1 changed files with 27 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
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`:
- 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.
- token: the user(name), authentication realm (pam), token id, and token secrey key (uuid)
- 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
2. In `backends/paasldap/config` (**Optional**):
- url: url to a PAAS-LDAP server API ie. `http://<paasldap-host>:8082`
3. In `handlers/auth`:
- 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)
4. In `application`:
- hostname - the ProxmoxAAS-Dashboard URL, ie `host.domain.tld` - hostname - the ProxmoxAAS-Dashboard URL, ie `host.domain.tld`
- domain - the base domain for the dashboard and proxmox, ie `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 `8080` - listenPort - the port you want the API to listen on, ie `8081`
- pveAPIToken - the user(name), authentication realm, token id, and token secrey key (uuid) 5. In `useriso`:
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: - node: host of storage with user accessible iso files
- username: root user name, typically `root@pam` - storage: name of storage with user accessible iso files
- password: root user password 4. Start the service using `node .`, or call the provided shell script, or use the provided systemctl service script
5. You may also wish to configure users at this point as well. An example user config is shown in the template.
6. 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