Skip to main content

Server Quickstart

Set up an Excalibur server for clients to connect.

Prerequisites​

You will require Python 3.11+ installed on your system to run the Excalibur server.

We also recommend using pipx to install the server, as it will allow you to run the server without requiring administrator privileges.

Installation​

First, download the Excalibur server, which is a .whl file. Once done, we can install the server.

If you are using pipx, you can run

pipx install [PATH_TO_WHEEL_FILE]

Check that the server is installed correctly by running

excalibur --version

You should see the version of the server printed to the console.

Setting Up​

Now we need to initialize the server by running

excalibur init

This will create a new folder excalibur-files in the current working directory. You should also notice a message like Account Creation Key Mnemonic followed by 24 words; these words are your Account Creation Key (ACK) mnemonic, which is needed to create an account from the client.

note

The ACK is actually a 256-bit (32-byte) random number, but it is represented as a mnemonic for ease of use.

Getting the ACK Mnemonic

If you want to see the ACK mnemonic again, use the command

excalibur user ack

This will print the ACK mnemonic to the console.

Configuration​

The configuration file is a TOML file named config.toml in the excalibur-files folder. There are a few key values that you might want to edit:

  • server.rate_limit.capacity and server.rate_limit.fill_rate: These control the rate limit for the server. The default values are 250 and 25 respectively.
  • security.session_duration: The duration of a login session in seconds. The default value represents 1 hour, but you can set it to a higher or lower value if you prefer.
  • security.key_strength: The size of the keys used for cryptographic operations, in bits. The default value of 128 bits should be both secure and performant, but if you prefer a higher security, you can set it to 192 or 256.

You should also notice that the security.opaque table has been populated. These values are used for the OPAQUE-3DH authentication system, a more modern augmented password-authenticated key exchange (aPAKE) protocol.

Legacy SRP Configuration

You might notice that there is a security.srp table in the configuration file. This is for the legacy Secure Remote Password (SRP) authentication system, which is still supported but not recommended for new deployments. If you want to use the legacy SRP system, you can set the security.srp.group value to small, medium, or large to control the security level.

Starting the Server​

To start the Excalibur server, run

excalibur start

You can check if the server is running by going to http://localhost:52419/api/well-known/version. You should see a response like the following:

{
    "version": "x.y.z",
    "commit": null
}
Host and Port

You might want to change the host and port that the server runs on. You can do this by setting specifying the --host and --port flags when starting the server. For example, to listen on all IPs and port 8080, run

excalibur start --host 0.0.0.0 --port 8080
note

To see all options that you can use when starting the Excalibur server, run

excalibur start --help

Congratulations! You have successfully set up an Excalibur server. Move on to the Client Quickstart to set up a client to connect to your server.