How to run the server?

The following is a guide how to run a local instance of the agdb_server on any platform/OS supported by Rust building from source.

Install git

From the officail source (opens in a new tab) (skip if you already have it).

Install Rust toolchain

From the official source (opens in a new tab) (mininum required version is 1.75.0).

Install `agdb_server`

For non-production use:

cargo install agdb_server

For production a manual build & install is recommended. You would build agdb_server from source in release mode with a custom pepper file. The pepper file located in sources as agdb_server/pepper contains a random 16 character value that is used internally to additionally "season" the encrypted passwords. When building for production you should change this value to a different one and keep the pepper file as secret in case you needed to rebuild the server or build a new version.

The steps for a production/manual build (use bash on Unix or git bash on Windows):

git clone https://github.com/agnesoft/agdb.git
cd agdb/
git checkout $(git describe --tags) # checkout the latest released version
echo "1234567891234567" > agdb_server/pepper #use a different value, this value will be a secret
cargo build --release -p agdb_server
mv target/release/agdb_server "<location available on your PATH>"
# Windows: target/release/agdb_server.exe

⚠️

Server with a different pepper value (e.g. default non-prod version) won't be able to decode passwords in the internal database. If you lose the pepper value of your server and need to rebuild it you should generate a new pepper and then you will need to create a new admin account (by changing the config value to a non-existent user) and using that account you can reset passwords of all your users via /api/v1/admin/user/{username}/change_password API (including the old admin account).

Run the server

agdb_server

The server upon starting will create few things in its working directory:

agdb_server.yaml: Configuration file. You can alter it as you wish. You would need to restart the server for the changes to take effect.
agdb_server.agdb (.agdb_server.agdb): Internal databse of the server (uses agdb itself) + its write ahead file (the dotfile).
agdb_data_dir/: Folder for stroing the user data. It can be changed in the configuration file (requires restart of the server).

and report where it listens at:

2024-01-26T17:47:30.956260Z  INFO agdb_server: Listening at localhost:3000

💡

You can prepare the configuration file before starting the server.

The config supports following values:

# agdb_server.yaml
bind: :::3000 # host address to listen on
address: localhost:3000 # address of incoming connections
basepath: "" # optional prefix to allow running behind a reverse proxy
admin: admin # the admin user that will be created automatically for the server, the password will be the same as name (admin by default, recommended to change after startup)
data_dir: agdb_server_data # directory to store user data

The server will be available on host:port as per configuration (i.e. localhost:3000 by default). The server logs every request-response as a single entry each time to STDOUT. You can redirect the output to a file, e.g. agdb_server > server.log. It is recommended to change the admin password from the default (same as admin username by default).

Test that the server is up with `curl`

curl -v localhost:3000/api/v1/status # should return 200 OK

Create a database user

It is recommended (but optional) to create a regular user rather than using the admin user (which is however still possible):

 # produce an admin API token, e.g. "bb2fc207-90d1-45dd-8110-3247c4753cd5"
token=$(curl -X POST -H 'Content-Type: application/json' localhost:3000/api/v1/user/login -d '{"username":"admin","password":"admin"}')
# using admin token to create a user
curl -X POST -H "Authorization: Bearer ${token}" localhost:3000/api/v1/admin/user/my_db_user/add -d '{"password":"password123"}'
# login as the new user and producing their token
token=$(curl -X POST -H 'Content-Type: application/json' localhost:3000/api/v1/user/login -d '{"username":"my_db_user","password":"password123"}')

Interact with the database server

You can either continue using curl, interactive OpenAPI GUI from any browser localhost:3000/api/v1 (provided by rapidoc) or choose one of the available API clients. The raw OpenAPI specification can be downloaded from the server at localhost:3000/api/v1/openapi.json as well.

Shutdown the server

The server can be shutdown with CTRL+C or programmatically posting to the shutdown endpoint as logged in server admin:

# this will produce an admin API token, e.g. "bb2fc207-90d1-45dd-8110-3247c4753cd5"
token=$(curl -X POST -H 'Content-Type: application/json' localhost:3000/api/v1/user/login -d '{"username":"admin","password":"admin"}')
curl -X POST -H "Authorization: Bearer ${token}" localhost:3000/api/v1/admin/shutdown

Quickstart How to Use Studio