Self-Host Server Setup
ℹ️ Requires an Organization plan
Technical Requirements
- A machine running latest version of Linux distribution (e.g. Ubuntu Server, CentOS, Alpine Linux)
- Docker-engine version > 23.0.5 (Installation instructions in this guide)
- Docker-compose version > 2.18.0 (Installation instructions in this guide)
- 2 CPU cores and at least 8 GiB RAM
- 30 GB storage on the server
- Minimum 80 GB additional disk storage for data
- (Optional) A user identity management service such as Azure AD or LDAP for SSO authentication.
Other Requirements
Make sure your firewall supports HTTP2 connections. Anchorpoint uses the gRPC protocol to communicate with the server, which is based on HTTP2. It has a fallback for an HTTP1 gateway, however gRPC improves the speed and effiency of realtime updates to the Anchorpoint client. We highly recommend that you start an Anchorpoint cloud trial to evaluate whether gRPC works in your environment.
Licensing
Licensing depends on the number of users you will have. You need to contact us for a quote. You can also request a free trial license to test the self hosted environment. We also offer volume discounts if your number of users is higher than 25. If you agree, we will send you a payment link. Once the payment is made, we will send you the license key.
Install the stack
In the following sections we describe the setup process using our cli tool. We have a look at optional components that can be used and how to setup alternative solutions (e.g. for the database).
Installing docker
You can install docker e.g. with apt (adjust for your linux distribution accordingly). The latest docker installations ship with docker compose v2 automatically.
sudo apt update
sudo apt install curl apt-transport-https ca-certificates software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce -y
Add the current user to the Docker group
sudo usermod -aG docker $USER
newgrp docker
Check if the user was added to the Docker group
groups $USER
To start docker as service automatically run
sudo systemctl enable docker
Setup folder structure
Create a folder on your additional attached disk storage for the data of the Anchorpoint stack. In our example the disk is mounted on /datadrive
mkdir /datadrive/anchorpoint
cd /datadrive/anchorpoint
Cli Tool
Download our cli tool for linux. A documentation of all its commands can be found here. The commands will be used in the following sections.
curl https://s3.eu-central-1.amazonaws.com/releases.anchorpoint.app/SelfHosted/ap-self-hosted-cli/ap-self-hosted-cli-linux-amd64 -o selfhost-cli
chmod +x selfhost-cli
Setup Environment variables before running cli install
You can setup environment variables in your .bash_profile so that you do not have to insert them for every cli command. We will set the install directory and the license key.
cd ~/
touch .bash_profile
vim ~/bash_profile
Add the following lines (press i for insert mode in vim):
export AP_INSTALL_DIR=/datadrive/anchorpoint/install
export AP_LICENSE=<your_license_key_here>
Press escape and save with :wq and call source:
source ~/bash_profile
Check AP_INSTALL_DIR and AP_LICENSE with
echo $AP_INSTALL_DIR
echo $AP_LICENSE
Installing into the data folder
Create a subfolder in your anchorpoint folder
mkdir /datadrive/anchorpoint/install
Call the selfhost-cli intall command
cd /datadrive/anchorpoint
./selfhost-cli install
Choose the domain where you want the backend to be reachable e.g. anchorpoint.example.com or a network IP address (e.g. 192.168.178.100). Do NOT add http:// or https:// at the start of the domain.
If you want to use https you have to enable SSL or use e.g. a load balancer for ssl termination or a reverse proxy. If you enable ssl you will be asked if you want to use Let's Encrypt to generate an SSL certificate and store it in the data/letsencrypt directory in your install directory. If you provide an email address for Let's Encrypt you will get notified about any certificate issues. Note that Let's Encrypt only works with a publicly available server. If you want to provide your own ssl certificates please choose no and follow the guide in "How to use your own ssl certificates" in the next section.
MinIO is the s3 bucket alternative that can be installed in the stack and will save its data to the data/minio directory in your install directory by default. If you plan to use another s3 provider you will have to choose "no" and adjust the environment file that will be generated in the install directory. Check the next section for more information.
Postgres is the database server that will handle the Anchorpoint database and the Keycloak database. By default, its data is stored in the data/postgres directory in your install directory. If you plan to use another postgres server you will have to choose "no" and adjust the environment file that will be generated. Check the next section for more information.
If you want to see metrics and search logs you can use grafana, prometheus and loki which can be auto installed via the cli tool. You can access grafana via SERVERURL/grafana after the stack is started. You can checkout our metrics documentation for more information about metrics and logs.
Check all your inputs and finish the install process. The cli tool will download the latest package and setup the docker-compose files and the needed directories for you. Before starting the stack please read the next section to make sure that your environment is correctly setup for your usecase.
Adjust the environment file before starting the stack
The install command will generate an .env file in your selected install directory. This environment file contains variables for each component of the stack. You can find a description for each section of the .env file here. Do not share this .env file as it contains many credentials.
| Name | Default Value | Description |
|---|---|---|
| Stack Global | ||
COMPOSE_PROJECT_NAME | ap_stack | The name of the stack for Docker Compose. |
| Domain | ||
DOMAIN_NAME | Domain from cli install | The domain or IP address where the stack is hosted. |
HTTP_PORT | 8080 or 443 from cli install | The port for HTTP / HTTPS traffic. |
GRPC_PORT | 9090 | The port for gRPC traffic. |
HTTP_SCHEME | http or https from cli install | The HTTP scheme used (http or https). |
| Traefik | ||
TRAEFIK_DATA_PATH | ./data/traefik | Path to store Traefik data. |
LETS_ENCRYPT_EMAIL | Set from cli install when provided | (Optional) Email for Let's Encrypt notifications. |
| Keycloak | ||
KEYCLOAK_USER | admin | Default admin user for Keycloak. |
KEYCLOAK_PASSWORD | Auto generated from cli install | Default admin password for Keycloak. |
ADMIN_CLI_CLIENT_SECRET | Auto generated from cli install | Secret for the admin CLI client. |
DASHBOARD_CLIENT_SECRET | Auto generated from cli install | Secret for the dashboard client. |
| Anchorpoint Backend | ||
LICENSE_KEY | Set from cli install | License key for the Anchorpoint Backend. |
DEFAULT_WORKSPACE_ID | Set from cli install | Identifier for the default workspace all users get invited to from the dashboard. |
DEFAULT_WORKSPACE_NAME | AP Workspace | Name of the default workspace on first creation. |
DASHBOARD_SESSION_SECRET | Auto generated from cli install | Secret for dashboard session. |
CRASH_REPORTING | false | Allow crash reporting to our servers for crashes in the desktop client. Note that crashes attach log data that can contain sensitive information |
EMAIL_HOST | Smpt email host | |
EMAIL_PORT | 25 | Smpt email port |
EMAIL_USER | Smpt email username | |
EMAIL_PASSWORD | Smpt email password | |
AP_UPDATES_DATA_PATH | ./data/ap_backend/updates | Path to provide client updates data. |
| Postgres | ||
POSTGRES_PASSWORD | Auto generated from cli install | Password for the PostgreSQL database. |
POSTGRES_USER | postgresuser | User for the PostgreSQL database. |
POSTGRES_ADDRESS | postgres | Address of the PostgreSQL database. |
POSTGRES_PORT | 5432 | Port for the PostgreSQL database. |
POSTGRES_DB | ap | Database name for PostgreSQL. |
POSTGRES_DATA_PATH | ./data/postgres | Path to store PostgreSQL data. |
| RabbitMq | ||
RABBITMQ_USER | aprabbitmq | User for RabbitMQ. |
RABBITMQ_PASSWORD | Auto generated from cli install | Password for RabbitMQ. |
RABBITMQ_ERLANG_COOKIE | Auto generated from cli install | Cookie secret for RabbitMQ. |
| MinIO | ||
MINIO_ACCESS_KEY | apminio | Access key for MinIO. |
MINIO_SECRET_KEY | Auto generated from cli install | Secret key for MinIO. |
MINIO_DOMAIN_NAME | Domain from cli install | Domain name for MinIO. |
MINIO_PORT | 9000 | Port for MinIO. |
MINIO_DASHBOARD_PORT | 9001 | Dashboard port for MinIO. |
MINIO_DATA_PATH | ./data/minio | Path to store MinIO data. |
MINIO_CREATE_BUCKET | true | Whether to create a MinIO bucket on startup. |
MINIO_CREATE_BUCKET_WITH_POLICY | true | Whether to create a MinIO bucket with a policy. |
MINIO_BUCKET_AS_PATH_STYLE | true | Whether MinIO uses path-style access. |
| Other S3 Provider | ||
S3_ACCESS_KEY | Access key for S3 storage. | |
S3_SECRET_KEY | Secret key for S3 storage. | |
S3_SERVER_URL | https://s3.eu-central-1.amazonaws.com | URL for S3 server. |
S3_INTERNAL_URL | s3.eu-central-1.amazonaws.com | Internal URL for S3 server. |
S3_EXTERNAL_URL | s3.eu-central-1.amazonaws.com | External URL for S3 server. |
S3_USE_SSL | true | Whether to use SSL for S3 connections. |
S3_BUCKET | ap | Bucket name for S3 storage. |
S3_REGION | Region for S3 storage. | |
S3_CREATE_BUCKET | false | Whether to create an S3 bucket on startup. |
S3_CREATE_BUCKET_WITH_POLICY | false | Whether to create an S3 bucket with a policy. |
S3_BUCKET_AS_PATH_STYLE | false | Whether S3 uses path-style access. |
| Grafana | ||
GRAFANA_USER_ID | 1000 | UserID for grafana container. |
GRAFANA_GROUP_ID | 1000 | GroupID for grafana container. |
GRAFANA_USER | admin | User for grafana login. |
GRAFANA_PASSWORD | Auto generated from cli install | Password for grafana login. |
GRAFANA_DATA_PATH | ./data/grafana | Path to store grafana data. |
PROMETHEUS_DATA_PATH | ./data/prometheus | Path to store prometheus data. |
LOKI_DATA_PATH | ./data/loki | Path to store loki data. |
(Optional) How to use your own ssl certificates
If you selected to use your own ssl certificates (self signed also possible) in the stack, you have to place your certificates in the data/traefik/certs directory in your install directory and adjust the data/traefik/dynamic_conf.yaml file in your install dictory to reference all your certificates. An example file content could look like this:
tls:
certificates:
- certFile: /data/traefik/certs/cert1.crt
keyFile: /data/traefik/certs/cert1.key
- certFile: /data/traefik/certs/cert2.crt
keyFile: /data/traefik/certs/cert2.key
Note that the path in the config file is the path to the certificates inside the docker container not the path at the host. So keep it as /data/traefik/certs/ in the dynamic_conf.yaml and only adjust the name of the certificate/s and the key/s. Also note that if you have intermediate certificates you have to create one crt file with first the server certificate followed by any intermediate certificates in the same file.
You can also find more information about the dynamic_conf.yaml on the traefik documentation here.
(Optional) How to send emails for user mentions
If you want the Anchorpoint backend to send emails when a user is invited or mentioned in a comment you have to setup the EMAIL_ environment variables for smtp. You can also adjust the email templates from config/ap_backend/templates/email directory.
(Optional) How to store data on a different path
If you want to change the data paths of Postgres, MinIO, Traefik, or the Anchorpoint Backend Client update folder, you can adjust the according ..._PATH environment variables before starting the stack.
(Optional) How to use a custom Postgres server
If you want to use your own postgres database server, do not choose postgres in the cli install command. Create two databases ap and keycloak on your database server. Setup the according POSTGRES_ environment variables in the .env file before starting the stack.
(Optional) How to make additional adjustments to the docker compose file
If you want to adjust the generated docker-compose file created by the cli tool, please use overwrites by creating a new yaml file next to the existing docker-compose file. If you directly change the original docker-compose file the cli update command will overwrite your changes. The cli start command will consider all compose files in your installation directory when starting the stack.
Start the stack
To start the stack you must use the cli tool start command.
./selfhost-cli start
Internally it will use docker compose up -d but it will also respect configration overwrites. An overview about the state of the containers will be printed. The ap_backend container will only start if the depending containers get into a healthy state. After all containers are started you can check if the Anchorpoint web dashboard is reachable under http{s}://{your_domain}/dashboard. Be aware that it might take a few minutes for the dashboard to be reachable.
Troubleshooting start problems
If the containers do not start, or you cannot reach them via your provided domain or IP address, first check the container log outputs. You can use docker ps -a to view all running containers. Copy the container id and use docker logs {container_id} to print the latest container log outputs.
Also check that your DNS records are setup correctly if you are using a custom domain and that your firewall allows connections on the http / https port, the gprc port, and the MinIO ports.
(Optional) Setup your SSO provider in Keycloak
Checkout our guide for SSO provider in Keycloak here.
Setup user accounts
Checkout our guide for managing users in your self hosted environment here. After you set up the user accounts, login via the Anchorpoint desktop client as described here.
How to update the stack
To update the stack, run the cli tool update command.
./selfhost-cli update
In case an update is available, it will download the latest version of the stack, including the latest Anchorpoint backend and client versions. The update will overwrite files in the installation directory, but will not change anything in your data directories. You can also use the check_update command to check if there is a new version available.
After the update is finsihed you can restart the stack by running the cli start command again. Note that while updating, the Anchorpoint clients will be in the offline mode. We generally recommend updating the stack after work when no users are currently using the application.
How to update your license
Adjust your .bash_profile AP_LICENSE environment variable:
cd ~/
touch .bash_profile
vim ~/bash_profile
ADjust the following line (press i for insert mode in vim):
export AP_LICENSE=<your_license_key_here>
Press escape and save with :wq and call source:
source ~/bash_profile
Check AP_LICENSE contains your new license key with
echo $AP_INSTALL_DIR
echo $AP_LICENSE
You can update the self-hosting license by using the cli tool update_license command.
./selfhost-cli update_license
The command will stop and remove the ap_backend container, patch the .env file LICENSE_KEY environment variable and recreate the ap_backend container for you. Note that this will also result in a short downtime while the ap_backend container is not running. Similar to updating, we recommend updating the license when no users are currently using the application.
How to stop the stack
To stop the stack you can use the cli tool stop command or use docker-compose stop in your installation directory.
Data that should be backed up regularly
You should regularly backup the data directories in your install directory. Also do a backup if you changed the data paths from their current location. You can restore the Anchorpoint backend state by restoring the database and MinIO directories.