diff --git a/docs/Configuration.md b/docs/Configuration.md index bb4efe0..81d7236 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -15,6 +15,7 @@ You can configure Headplane using environment variables. - **`CONFIG_FILE`**: The path to the Headscale `config.yaml` (default: `/etc/headscale/config.yaml`). - **`HEADSCALE_CONFIG_UNSTRICT`**: This will disable the strict configuration loader (default: `false`). - **`COOKIE_SECURE`**: This option enables the `Secure` flag for cookies, ensuring they are sent only over HTTPS, which helps prevent interception and enhances data security. It should be disabled when using HTTP instead of HTTPS (default: `true`). +- **`LOAD_ENV_FILE`**: Tell Headplane to read the `.env` file and load it into the environment (default: `false`). #### Docker Integration The Docker integration allows Headplane to manage the Headscale docker container. diff --git a/docs/integration/Native.md b/docs/integration/Native.md index 06ef23b..a9d6646 100644 --- a/docs/integration/Native.md +++ b/docs/integration/Native.md @@ -10,19 +10,60 @@ to undefined behavior or the service not restarting. ### Deployment -Follow the instructions to install Headscale from the -[Linux Installation Guide](https://headscale.net/running-headscale-linux/). As -of now, Headplane requires Node.js 20 to be installed on the system. Once you -are ready, clone the repository (`git clone https://github.com/tale/headplane`), -install dependencies (`npm install`), build the project (`npm run build`), and -start the server (`npm start`). +1. Follow the instructions to install Headscale from the +[Linux Installation Guide](https://headscale.net/setup/install/official). + +2. Install [Node.js](https://nodejs.org/en/download/package-manager) +version 20 or higher (your package manager most likely already has this). + +3. Install [PNPM](https://pnpm.io/installation). This is required +as Headplane has issues running correctly when installed and built via NPM or Yarn. + +4. Clone the Headplane repository, install dependencies, and build the project: +```sh +git clone https://github.com/tale/headplane # (or clone via SSH) +cd headplane +pnpm install +pnpm build +``` + +### Running Headplane +Start Headplane with `node build/headplane/server.js`. + +Headplane does need various environment variables to run correctly. The required +variables can be found in the [Configuration](/docs/Configuration.md) guide. +If you choose to do this with a `.env` file, you can use the `LOAD_ENV_FILE` +variable to tell Headplane to load the file. + +Finally, make sure to set `HEADSCALE_INTEGRATION=proc` to take advantage +of controlling Headscale natively on Linux. + +```sh +LOAD_ENV_FILE=true node ./build/headplane/server.js +``` > If you'd like, you can turn this into a `systemd` unit to manage the service. > I plan to provide packages and unit files to make this easier in the future. -When running Headplane, you'll need to set environment variables to configure -the application. The `HEADSCALE_INTEGRATION` variable should be set to `proc`. +### Cannot find ./build directory? +Headplane expects the `build` directory to be present when running the server. +The structure of this folder is very important and should not be tampered with. +If you would like to keep the build directory in a different location, you can +set the `BUILD_PATH` environment variable to the path of the build directory +at runtime. -> For a breakdown of each configuration variable, please refer to the -[Configuration](/docs/Configuration.md) guide. -> It explains what each variable does, how to configure them, and what the default values are. +```sh +LOAD_ENV_FILE=true BUILD_PATH=/path/to/build node ./build/headplane/server.js +``` + +### Changing Headplane's Path from `/admin` +Additionally, because you are building Headplane from source, you're able to +change the default path that Headplane is served from. This can be done by +specifying the `__INTERNAL_PREFIX` environment variable, when building. + +```sh +__INTERNAL_PREFIX=/my-admin-path pnpm build +``` + +> Keep in mind that this is very much an experimental feature. Things can easily +> break and until it's more stable, it's not recommended to use in production.