Bare metal

Install prerequisites

• Git: official source (skip if you already have it)
• Rust: official source
• OPTIONAL, REQUIRED FOR STUDIO Node.js: official source
• OPTIONAL, UNIX ONLY, REQUIRED FOR TLS CMake: official source
• OPTIONAL, WINDOWS ONLY, REQUIRED FOR TLS Microsoft Build Tools (includes CMake): official source

Install agdb_server

cargo install agdb_server --features "tls studio"
    # The `tls` feature is optional and can be omitted if TLS support is not needed. Requires CMake and on Windows also MSVC.
    # The `studio` feature is optional can be omitted if you do not need or want server GUI. Requires `pnpm`.

You can also build the server manually. One advantage is that you can use a custom pepper value and bake it into the binary instead of using runtime configured value. The pepper file is located in sources as agdb_server/pepper and 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. It can also be changed via configuration during runtime.

The steps for a 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 --features "tls studio"
    # The `tls` feature is optional and can be omitted if TLS support is not needed. Requires CMake and on Windows also MSVC.
    # The `studio` feature is optional can be omitted if you do not need or want server GUI. Requires `pnpm`.
mv target/release/agdb_server "<location available on your PATH>"
# Windows: target/release/agdb_server.exe

Alternatively you can use the default pepper value but specify in configuration the "pepper_path" from which the pepper would be loaded during runtime. This file and location should be treated as secret. All the caveats of manual build still apply including the recovery steps in case the pepper value is lost.

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 or prepare one in advance. You would need to restart the server for the changes to take effect.
• agdb_data_dir/: Folder for storing the user data. It can be changed in the configuration file (requires restart of the server and possibly moving the internal database and data, if any, to the new location).
• agdb_data_dir/agdb_server.agdb (agdb_data_dir/.agdb_server.agdb): Internal database of the server (uses agdb itself) + it's write ahead file (the dotfile).

and report where it listens at:

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

Please refer to the server reference for the configuration options.

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