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 20 and 1 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.srp.group: The size of the Secure Remote Password (SRP) group used for authentication. The default value of small is sufficient for most use cases, but if you prefer a higher security, you can set it to medium or large.

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.