---
title: "How to run the server?"
description: "How to run the server, Agnesoft Graph Database"
---

import { Callout, Steps } from "nextra/components";

# 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.

<Steps>

### Install git

From the [officail source](https://git-scm.com/) (skip if you already have it).

### Install Rust toolchain

From the [official source](https://www.rust-lang.org/tools/install) (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):

```bash
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
```

<Callout type="warning">
    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).
</Callout>

### Run the server

```bash
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
```

<Callout>
    You can prepare the configuration file before starting the server.
</Callout>

The config supports following values:

```yaml
# 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`

```bash
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):

```bash
 # 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](/api-docs/openapi). 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:

```bash
# 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
```

</Steps>
