From 0013833bce0ecf10b0975e7b976190fddd23e4a0 Mon Sep 17 00:00:00 2001 From: Arthur Lu Date: Tue, 16 Jan 2024 22:36:21 +0000 Subject: [PATCH] update README --- README.md | 44 +++++++++++++++++++++++++++----------------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index ba5a569..27c4f1d 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,16 @@ # 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. -## Prerequisites +## Installation + +### Prerequisites - [ProxmoxAAS-Dashboard](https://git.tronnet.net/tronnet/ProxmoxAAS-Dashboard) - Proxmox VE Cluster (v7.0+) - Reverse proxy server which can proxy the dashboard and API - FQDN - 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: 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 @@ -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` 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` 2. Run `npm install` to initiaze the package requirements -3. Copy `template.localdb.json` as `localdb.json` and modify the following values under `pveAPIToken`: - - pveAPI - the URI to the Proxmox API, ie `:8006/api2/json` or `/api2/json` if Proxmox VE is behind a reverse proxy. - - 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 `8080` - - pveAPIToken - the user(name), authentication realm, token id, and token secrey key (uuid) -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: - - username: root user name, typically `root@pam` - - password: root user password -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 +3. Copy `template.config.json` as `config.json` and modify the following values: + 1. In `backends/pve/config`: + - url: the URI to the Proxmox API, ie `http://:8006/api2/json` or `http:///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://: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` + - 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: ``` server { @@ -56,5 +64,7 @@ server { ``` 2. Start nginx with the new configurations -## Result -After these steps, the ProxmoxAAS Dashboard should be available and fully functional at `paas.` or `paas./dashboard/`. \ No newline at end of file +### Result +After these steps, the ProxmoxAAS Dashboard should be available and fully functional at `paas.` or `paas./dashboard/`. + +# Backends \ No newline at end of file