Quick start of Odyssey usage¶

There are several ways to start using Odyssey:

• debian and ubuntu packages from PGDG
• pre-built public docker image
• local build of Docker image
• local build

Debian and Ubuntu packages¶

Odyssey is available via PGDG repository.

Learn more about the repository here: https://wiki.postgresql.org/wiki/Apt

To use the package, add PGDG:

$ sudo apt install -y postgresql-common ca-certificates
$ sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh

And then install Odyssey:

$ sudo apt-get install -y odyssey

The package will create simple config at /etc/odyssey/odyssey.conf and systemd service, that can be controlled with:

$ sudo systemctl start odyssey
$ sudo systemctl stop odyssey
$ sudo systemctl reload odyssey
$ sudo systemctl status odyssey

Note: new releases can be available at repository after some time, day or two after the release on Github.

Pre-built Docker image¶

The easiest way to get started with Odyssey is to use our pre-built Docker images from GitHub Container Registry.

Only version starts with 1.5.0 are supported.

Quick start with default configuration¶

There are public images based on alpine on ghcr.io/yandex/odyssey. You can try it with:

$ docker run -d \
   --name odyssey \
   -e PG_HOST=your-postgres-host \
   -e DB_NAME=mydb \
   -e USER_NAME=myuser \
   -e USER_AUTH_TYPE=none \
   --network host \
   ghcr.io/yandex/odyssey:1.5.0-rc2

Or with full config mount to /etc/odyssey/odyssey.conf:

$ docker run -d \
   --name odyssey \
   -v ./config.conf:/etc/odyssey/odyssey.conf \
   --network host \
   ghcr.io/yandex/odyssey:1.5.0-rc2

This will run Odyssey on port 6432, that is connected to your-postgres-host.

$ psql 'host=localhost port=6432 user=myuser dbname=mydb' -c 'select 42 as the_value'
 the_value 
-----------
        42
(1 row)

Available image tags¶

• latest - Latest stable release
• edge - Latest development build from master branch
• 1.5.0 - Specific stable version
• 1.5.0-rc1 - Release candidate
• 1.5 - Latest patch version in 1.5.x series
• 1 - Latest minor version in 1.x series

Environment Variables Reference¶

Global Settings¶

Listen Configuration¶

Storage Configuration¶

Database and User Configuration¶

Virtual Database (Console) Configuration¶

Advanced Configuration¶

Runtime Mode¶

The RUN_MODE variable controls how Odyssey runs:

• production (default): Runs as unprivileged odyssey user
• test: Runs as root (for testing with /proc access)
• debug: Runs as root with debug settings
• root: Runs as root

Warning: test, debug, and root modes should only be used in testing environments!

Docker build¶

After that you can simply do:

make quickstart

This will create and run odyssey as odyssey, with base config from docker/quickstart/config.conf.

This configuration writes logs to the stdout, so to view the logs, you can do:

docker logs odyssey

Build with your config¶

You can start odyssey with your config. You need to do:

docker build -f docker/quickstart/Dockerfile . --tag=odyssey

There are two ways to achieve this. The first method is to modify the default configuration. Simply add new parameters to the "docker run" command:

docker run -e LISTEN_PORT=1234 \
        --rm \
        --name "odyssey" \
        odyssey

You can find other settings with default values that you can modify below:

LOS_SESSION=yes
LOS_QUERY=no
LISTEN_HOST="*"
LISTEN_PORT=6432
PG_HOST="127.0.0.1"
PG_PORT=5432
DB_NAME=default
USER_NAME=default
USER_AUTH_TYPE="clear_text"
USER_PASSWORD="password"
POOL_TYPE="session"
POOL_SIZE=1
VIRTUAL_DB_NAME="console"
VIRTUAL_DB_USER_NAME="console"

Another way is to use volume to start with your own config file. Simply replace PATH_TO_YOUR_CONFIG with the path to your configuration file and run this command:

docker run -d \
        --rm \
        --name "odyssey" \
        -v PATH_TO_YOUR_CONFIG:/etc/odyssey/odyssey.conf \
        odyssey

Local build¶

Currently Odyssey runs only on Linux. Supported platforms are x86/x86_64.

To make minimal build on ubuntu you will need:

sudo apt-get install openssl postgresql-server-dev-all build-essential cmake

Optional dependencies:

# For systemd notify support (online restart)
sudo apt-get install libsystemd-dev

After that you can simply do:

make build_release

This will create executable odyssey in build/sources, which can be run with config like:

build/sources/odyssey config.conf

daemonize yes

log_format "%p %t %l [%i %s] (%c) %m\n"
log_file "/var/log/odyssey.log"
log_to_stdout no
log_config yes
log_debug no
log_session yes
log_stats no
log_query no

coroutine_stack_size 24

listen {
    host "0.0.0.0"
    port 6432
}

storage "postgres_server" {
    type "remote"
    host "[127.0.0.1]:5432"
}

database "postgres" {
    user "postgres" {
        authentication "none"
        storage "postgres_server"
        pool "session"
    }
}