LinkAhead is configured via so-called profiles. A profile is a directory that contains at least a profile.yml file. Via this file the most important configuration options can be set.

The profile that is used when LinkAhead starts is configured in the file /etc/linkahead/linkahead.conf. After a fresh installation, this is the path to the default profile (e.g. /usr/share/linkahead/profiles/default/profile.yml).

You should copy the default profile to get a starting point:

cp -r /usr/share/linkahead/profiles/default ~/.config/linkahead

These paths are examples but may depend on your system and your preferences.

Afterwards, set the path in the configuration file /etc/linkahead/linkahead.conf to your new profile.

Standard profiles

The standard profiles in LinkAhead are:


The default profile simply uses the defaults. This means, above all: no anonymous user, persistent data, and authentication to the IndiScale server must be provided to obtain the Docker images. This profile is a solid base to set up your own configuration in a production environment.


The trial profile is the default profile for the gratis trial package of LinkAhead. It is similar to the default profile, but has a few settings changed to simplify the first steps: the anonymous user is enabled and mails sent by the server will be written to files in /tmp/mail/ inside the Docker container instead of sent over the network. There is no explicit registry server: the docker image is obtained from the default Docker Hub.


The debug profile is useful for writing scripts and tests, and for debugging. Debugging in the server is enabled, the anonymous user is disabled and an empty database is loaded on every restart.


The demo profile is the one which is used on the demo server at It comes with customized content both for the database content and the web frontend, to provide user interfaces and content for the demo tour. Because the server is restarted periodically, the profile is set to restore its content upon startup. The anonymous user is enabled.

Restore data

LinkAhead allows to restore data during start up. This can be enabled with the restore: true option in the profile.yml. Corresponding files need to be placed in custom/other/restore/ in the profile directory. A typical use case is to place the files created with linkahead backup here.

To disable restoring, set the option to false and move the custom/other/restore/ folder to some other location.

SSL Encryption

In order to use HTTPS (which is strongly recommended) you need to provide a certificate that is used by the server.

Creating the Java Key Store

The LinkAhead server expects a Java Key Store named caosdb.jks. In the following we will distinguish two cases:

  1. You have a valid certificate that you want to provide.

  2. You want to create and use a self-signed certificate.

Note, that the first option is strongly recommended (ask you IT-department, if you do not know how to get a valid certificate).

Option 1: Using an existing certificate

Suppose you have a certificate and private key file named fullchain.pem and privkey.pem, respectively, you can create a key store from those files.

Note that the full certificate chain should be included into the fullchain.pem, not only the server certificate itself.

During the execution of the following two commands you will be asked to supply a password with at least six characters. Use the same password for both commands and note that you will need it in a later step again.

openssl pkcs12 -export -inkey privkey.pem -in fullchain.pem -out all-certs.pkcs12
keytool -importkeystore -srckeystore all-certs.pkcs12 -srcstoretype PKCS12  -deststoretype pkcs12 -destkeystore caosdb.jks

keytool is provided by openjdk-14-jre-headless, for example.

Option 2: Creating a self-signed certificate.

In order to create a self-signed certificates (not recommended for production use) you can do (You can replace localhost by your host name):

mkdir certificates; cd certificates
keytool -genkey -keyalg RSA -alias selfsigned -keystore caosdb.jks -validity 375 -keysize 2048 -ext san=dns:localhost
keytool -importkeystore -srckeystore caosdb.jks -destkeystore caosdb.p12 -deststoretype PKCS12 -srcalias selfsigned
openssl pkcs12 -in caosdb.p12 -nokeys -out caosdb.cert.pem

During the execution of the following two commands you will be asked to supply a password with at least six characters. Use the same password for both commands and note that you will need it in a later step again.

The last command exports only the public part of the certificate. The resulting cert.pem can safely be given to users to allow SSL verification.

Using the Java Key Store

Place the resulting file caosdb.jks in the profile directory under the path custom/other/cert/caosdb.jks. All certificate files should be readable/accessible only by the user that runs the LinkAhead server.

The password to the certificate needs to be supplied to the LinkAhead server via a configuration file. For example, create a file custom/caosdb-server/conf/ext/server.conf.d/90-keystore.conf with the content


where you replace <password> with the password that you used when creating the key store.

Now, you can restart LinkAhead: sudo systemctl restart linkahead. If you used Option 1 above with a certificate that is signed by a known Certificate Authority, you can now access LinkAhead with a browser (Unless you changed the port: https://domain:10443) and SSL will work fine.

If you used a self-signed certificate, the browser will warn you that The certificate is not trusted because it is self-signed..

In order to allow the Python client to use SSL encryption with a self-signed certificate, you need to supply the public part, that you created above: caosdb.cert.pem. Provide the path to that file in the configuration file of the client pycasodb.ini: cacert=/path/to/caosdb.cert.pem


Check what certificate is delivered by the server

In order to exclude the possibility that the configuration did not go well (wrong filename, directory, …), you should check what certificate is provided by LinkAhead. When you open the URL with a browser and get a Security Warning, ask the browser to show the certificate (Firefox: Click on ‘Advanced…’ and then ‘View Certificate’ below the Error Code). If it simply says ‘localhost’ for Subject Name without any further Information like organization or state, it is probably the default self-signed certificate that is served by LinkAhead and the configuration is incorrect. Check paths and naming of files carefully.

Server cannot be reached

If for example a browser cannot establish a connection to the LinkAhead server, check the logs (e.g. journalctl -u linkahead -b). If you see the line keystore password was incorrect then the password to access the Java Key Store supplied to LinkAhead is incorrect. Check whether the file containing the password is in the server configuration folder and whether the password is spelled correctly.

Clients cannot connect

Make sure that your clients use the fully qualified domain name (e.g. in their configuration. The name must equal the one of the certificate.

You may need to add the certificate of the CA (Certificate Authority) in the configuration of your client, if shipped with your operating system.


By default, the server will only listen on the loopback device (localhost). You can expand this by setting the bind_ip value in the network section of profile.yml. Specify the IP of the desired interface or use an empty string “” (equivalent to to listen on all interfaces.