mirror of
https://github.com/tale/headplane.git
synced 2026-07-26 07:48:14 +00:00
chore: format everything with oxfmt
This commit is contained in:
Aarnav Tale
@@ -4,12 +4,15 @@ description: Common issues and their solutions
|
||||
---
|
||||
|
||||
# Common Issues and Their Solutions
|
||||
|
||||
This document outlines some common issues users may encounter while using Headplane, along with their solutions.
|
||||
|
||||
## Login does not work
|
||||
|
||||
::: tip
|
||||
Headplane tries to detect misconfigurations and will surface a warning banner on
|
||||
the login page if it detects any abnormalities. You may see a banner like this:
|
||||
|
||||
<figure>
|
||||
<img class="dark-only" src="../assets/login-banner-dark.png" />
|
||||
<img class="light-only" src="../assets/login-banner-light.png" />
|
||||
@@ -21,5 +24,6 @@ If you attempt to log in to Headplane but nothing happens, it may be due to a
|
||||
misconfiguration of the server cookie settings. In your Headplane configuration,
|
||||
ensure that `server.cookie_secure` is set appropriately based on how you are
|
||||
accessing Headplane:
|
||||
|
||||
- Serving over HTTPS: `cookie_secure` should be enabled (`true`).
|
||||
- Serving over HTTP: `cookie_secure` should be disabled (`false`).
|
||||
|
||||
@@ -32,4 +32,3 @@ features:
|
||||
details: "Manage settings hidden behind Headscale configuration such as DNS, networking, auth controls, etc."
|
||||
icon: "📝"
|
||||
---
|
||||
|
||||
|
||||
+18
-13
@@ -12,15 +12,16 @@ set up your configuration file and then pick the installation method that best
|
||||
suits your needs.
|
||||
|
||||
## Configuration
|
||||
|
||||
Headplane requires a configuration file to operate. A
|
||||
[sample file](https://github.com/tale/headplane/blob/main/config.example.yaml)
|
||||
is available to use as a starting point. Some of the important fields include:
|
||||
|
||||
| Field | Description |
|
||||
|---------------------|--------------------------------------------------------|
|
||||
| **`headscale.url`** | Point to your Headscale server (e.g., `http://headscale.example.com` or `http://headscale:8080` in Docker). |
|
||||
| **`server.cookie_secret`** | Used to encrypt cookies. You can generate a random string using a command like `openssl rand -base64 24`. |
|
||||
| **`server.data_path`** | Just a path to keep in mind, especially if you're using Docker. |
|
||||
| Field | Description |
|
||||
| -------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
||||
| **`headscale.url`** | Point to your Headscale server (e.g., `http://headscale.example.com` or `http://headscale:8080` in Docker). |
|
||||
| **`server.cookie_secret`** | Used to encrypt cookies. You can generate a random string using a command like `openssl rand -base64 24`. |
|
||||
| **`server.data_path`** | Just a path to keep in mind, especially if you're using Docker. |
|
||||
|
||||
The configuration file is rather complicated and has many more options. Refer to
|
||||
the [Configuration](../configuration/index.md) guide for a detailed explanation of all
|
||||
@@ -28,24 +29,28 @@ the available options, as well as guidance on securely setting up your values
|
||||
through secret path options and environment variables.
|
||||
|
||||
## Deployment Methods
|
||||
|
||||
Headplane can be deployed in several different ways, each with its own set of
|
||||
advantages and trade-offs. Choose the method that best fits your needs:
|
||||
|
||||
### [Docker](./docker.md): Fast and easy deployment using Docker
|
||||
- Recommended for most users due to its simplicity and ease of use.
|
||||
- Allows for advanced features like network management and remote web SSH.
|
||||
- Requires Docker and Docker Compose to be installed.
|
||||
|
||||
- Recommended for most users due to its simplicity and ease of use.
|
||||
- Allows for advanced features like network management and remote web SSH.
|
||||
- Requires Docker and Docker Compose to be installed.
|
||||
|
||||
---
|
||||
|
||||
### [Native Mode](./native-mode.md): Direct installation on a server
|
||||
- Suitable for users who prefer not to use Docker.
|
||||
- Allows for advanced features like network management and remote web SSH.
|
||||
- Requires manual setup of dependencies and environment.
|
||||
|
||||
- Suitable for users who prefer not to use Docker.
|
||||
- Allows for advanced features like network management and remote web SSH.
|
||||
- Requires manual setup of dependencies and environment.
|
||||
|
||||
---
|
||||
|
||||
### [Limited Mode](./limited-mode.md): Quick and easy deployment with minimal features
|
||||
- Ideal for testing or simple environments and not intended for production use.
|
||||
- Lacks any advanced functionality or integrations such as network management
|
||||
|
||||
- Ideal for testing or simple environments and not intended for production use.
|
||||
- Lacks any advanced functionality or integrations such as network management
|
||||
or remote web SSH.
|
||||
|
||||
@@ -12,16 +12,18 @@ deployment. Limited mode lacks advanced features such as network management,
|
||||
remote web SSH, and more.
|
||||
:::
|
||||
|
||||
Limited Mode is good for users who want to test out the *basic* functionality
|
||||
Limited Mode is good for users who want to test out the _basic_ functionality
|
||||
provided by Headplane. It only interacts with the Headplane API and lacks all
|
||||
advanced features, making it suitable for local testing and development.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker (and optionally Docker Compose)
|
||||
- Headscale version 0.26.0 or later installed and running
|
||||
- A [completed configuration file](/index.md#configuration) for Headplane.
|
||||
- A [completed configuration file](/index.md#configuration) for Headplane.
|
||||
|
||||
## Installation
|
||||
|
||||
::: tip
|
||||
If you want to test Limited Mode without Docker, you can follow the
|
||||
[Native Mode](./native-mode.md) installation guide and simply avoid setting
|
||||
@@ -29,6 +31,7 @@ up any of the advanced features.
|
||||
:::
|
||||
|
||||
Running Headplane in Limited Mode is as simple as running 1 command:
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
-p 3000:3000 \
|
||||
@@ -44,6 +47,7 @@ storage location for Headplane to store its own data. You can also change the
|
||||
port mapping if you want to run it on a different port.
|
||||
|
||||
### Optional: Docker Compose
|
||||
|
||||
If you prefer using Docker Compose, here is a minimal example of a
|
||||
`compose.yaml` file that runs Headplane in Limited Mode:
|
||||
|
||||
@@ -54,10 +58,10 @@ services:
|
||||
container_name: headplane
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- '3000:3000'
|
||||
- "3000:3000"
|
||||
volumes:
|
||||
- '/path/to/your/config.yaml:/etc/headplane/config.yaml'
|
||||
- '/path/to/data/storage:/var/lib/headplane'
|
||||
- "/path/to/your/config.yaml:/etc/headplane/config.yaml"
|
||||
- "/path/to/data/storage:/var/lib/headplane"
|
||||
```
|
||||
|
||||
## Accessing Headplane
|
||||
@@ -83,4 +87,3 @@ Limited Mode also technically supports
|
||||
[Single Sign-On (SSO) authentication](../features/sso.md), but some parts of it
|
||||
may not work as expected. For a full-featured experience with SSO, please use
|
||||
one of the other installation methods.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user