Server Setup#
ℹ️ Requires an Organization plan
Technical Requirements#
The server can be installed on any system that meets the following requirements. In addition, a user identity management service such as Azure AD or LDAP can be provided for authentication.
AWS or other Cloud Provider#
One EC2 instance (at least T3 large for about 15 users)
S3 storage for metadata such as project icons
PostgreSQL (e.g. AWS RDS) (optional, default is a postgres server running inside the docker compose stack)
Email service (optional)
None Cloud Provider#
Machine running latest version of Linux (e.g. Ubuntu Server, CentOS, Alpine Linux)
Docker-engine version > 23.0.5
Docker-compose version > 2.18.0
Other Requirements#
Make sure your firewall supports HTTP2 connections. Anchorpoint uses the gRPC protocol to communicate with the server, which is based on HTTP2. We highly recommend that you start an Anchorpoint cloud trial to evaluate whether it will work in your environment.
Getting started#
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).
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.
Cli Tool#
Download our cli tool for linux here. A documentation of all its commands can be found here. The commands will be used in the following sections.
Install the stack#
Create a folder where you want to install the docker compose stack into. Start the cli with the install command. Provide your trial or subscription license key that you received from us. Set the install directory that you have created before.
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 on your cloud provider or 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 config/letsencrypt directory in your install directory. If you provide an email address for Let’s Encrypt you will get notified about any certificate issues. 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 |
||
|
|
The name of the stack for Docker Compose. |
Domain |
||
|
Domain from cli install |
The domain or IP address where the stack is hosted. |
|
|
The port for HTTP / HTTPS traffic. |
|
|
The port for gRPC traffic. |
|
|
The HTTP scheme used (http or https). |
Traefik |
||
|
|
Path to store Traefik data. |
|
Set from cli install when provided |
(Optional) Email for Let’s Encrypt notifications. |
Keycloak |
||
|
|
Default admin user for Keycloak. |
|
Auto generated from cli install |
Default admin password for Keycloak. |
|
Auto generated from cli install |
Secret for the admin CLI client. |
|
Auto generated from cli install |
Secret for the dashboard client. |
Anchorpoint Backend |
||
|
Set from cli install |
License key for the Anchorpoint Backend. |
|
Set from cli install |
Identifier for the default workspace all users get invited to from the dashboard. |
|
|
Name of the default workspace on first creation. |
|
Auto generated from cli install |
Secret for dashboard session. |
|
false |
Allow crash reporting to our servers for crashes in the desktop client. Note that crashes attach log data that can contain sensitive information |
|
Smpt email host |
|
|
|
Smpt email port |
|
Smpt email username |
|
|
Smpt email password |
|
|
|
Path to provide client updates data. |
Postgres |
||
|
Auto generated from cli install |
Password for the PostgreSQL database. |
|
|
User for the PostgreSQL database. |
|
|
Address of the PostgreSQL database. |
|
|
Port for the PostgreSQL database. |
|
|
Database name for PostgreSQL. |
|
|
Path to store PostgreSQL data. |
RabbitMq |
||
|
|
User for RabbitMQ. |
|
Auto generated from cli install |
Password for RabbitMQ. |
|
Auto generated from cli install |
Cookie secret for RabbitMQ. |
MinIO |
||
|
|
Access key for MinIO. |
|
Auto generated from cli install |
Secret key for MinIO. |
|
Domain from cli install |
Domain name for MinIO. |
|
|
Port for MinIO. |
|
|
Dashboard port for MinIO. |
|
|
Path to store MinIO data. |
|
|
Whether to create a MinIO bucket on startup. |
|
|
Whether to create a MinIO bucket with a policy. |
|
|
Whether MinIO uses path-style access. |
Other S3 Provider |
||
|
Access key for S3 storage. |
|
|
Secret key for S3 storage. |
|
|
|
URL for S3 server. |
|
|
Internal URL for S3 server. |
|
|
External URL for S3 server. |
|
|
Whether to use SSL for S3 connections. |
|
|
Bucket name for S3 storage. |
|
Region for S3 storage. |
|
|
|
Whether to create an S3 bucket on startup. |
|
|
Whether to create an S3 bucket with a policy. |
|
|
Whether S3 uses path-style access. |
Grafana |
||
|
|
UserID for grafana container. |
|
|
GroupID for grafana container. |
|
|
User for grafana login. |
|
Auto generated from cli install |
Password for grafana login. |
|
|
Path to store grafana data. |
|
|
Path to store prometheus data. |
|
|
Path to store loki data. |
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 and adjust the data/traefik/certs/dynamic_conf.yaml file 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 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.
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.
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.
How to use other S3 provider instead of MinIO#
If you want to use S3 from your cloud provider of choice, do not choose minio in the cli install command. Setup a bucket on your cloud provider and make sure that you set the bucket policy to:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": "*",
"Action": [
"s3:GetObjectVersion",
"s3:GetObject"
],
"Resource": "{bucket_resource_id}/*/public/*"
}
]
}
and that you create a policy for the user of the credentials (S3_ACCESS_KEY / S3_SECRET_KEY) with:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:*"
],
"Resource": [
"{bucket_resource_id}",
"{bucket_resource_id}/*"
]
}
]
}
After you created the bucket please set the according S3_ environment variables in the .env. To test if your setup is working correctly you can first check the logs of the ap_backend container if the connection to the bucket could be created after you started the stack. You can then change your avatar in the Anchorpoint desktop client and check if a file is uploaded into the bucket. To test if the credentials and their policies are working correctly, setup a project in the Anchorpoint desktop client and change the project’s icon. Check if a file was uploaded to the bucket.
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.
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. 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.
Setup your SSO provider in Keycloak (optional)#
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. 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.
How to update your license#
You can update the self-hosting license by using the cli tool update_license command. 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.