nginx

The HTTP front-end runs on nginx. Either install nginx or OpenResty with the following additional modules:

Installation on FreeBSD

On FreeBSD, the full package can be installed with:

# pkg install www/nginx-full www/lua-resty-core

If you use a custom nginx package or build from source, make sure that all required modules are included. Build the port with:

# cd /usr/local/ports/www/nginx/
# make config

Select at least the following modules:

  • HTTP_REALIP

  • FORMINPUT

  • HEADERS_MORE

  • LUA

  • POSTGRES

  • SET_MISC

Then, build the port:

# make
# make install

Installation on Linux

On Linux, you probably prefer OpenResty. Binary packages are available for most distributions, but do not inluce the requires PostgreSQL module. Therefore, OpenResty has to be build from source.

At first, install all dependencies. On Debian:

$ sudo apt-get install libpcre3-dev libssl-dev perl make build-essential curl postgresql-contrib

On CentOS/RHEL, run instead:

$ sudo dnf install pcre-devel openssl-devel gcc curl postgres-devel

Then, download, unpack, and compile OpenResty:

$ wget https://openresty.org/download/openresty-VERSION.tar.gz
$ tar xfvz openresty-VERSION.tar.gz
$ cd openresty-VERSION/
$ ./configure --prefix=/usr/local/openresty \
              --with-luajit \
              --with-pcre-jit \
              --with-ipv6 \
              --with-http_iconv_module \
              --with-http_realip_module \
              --with-http_postgres_module \
              --j2
$ sudo make -j2
$ sudo make install

OpenResty is installed to /usr/local/openresty/, but you can choose any other path (for instance, /opt/openresty/).

Configuration

Copy the file nginx.conf and directory openadms-server from the GitHub repository to /usr/local/etc/nginx/ (FreeBSD) or /etc/nginx/ (Linux) and alter the configuration to your set-up. You have to update at least the name of the user the nginx process is running under, the connection details of your PostgreSQL database, and the actual server name:

user www;   # User to run nginx process under.

http {
    # PostgreSQL connection details. Change "localhost" to the IP address of
    # your database instance, if it is not running on the same host.
    #
    # dbname:   PostgreSQL database name.
    # user:     PostgreSQL user name.
    # password: PostgreSQL password.
    upstream postgresql {
        postgres_server     localhost dbname=timeseries user=<username> password=<password>;
        postgres_keepalive  max=200 overflow=reject;
    }

    server {
        server_name  www.example.com;   # CHANGE TO YOUR SERVER NAME!
    }
}

Access Restriction

The API uses HTTP BasicAuth for access restriction. Clients must send an authorisation header with encoded user name and password. Store login credentials in /usr/local/etc/nginx/.htpasswd. If you use a different path, change openadms-server/api.conf accordingly. You can use security/py-htpasswd to generate a .htpasswd, or simply run OpenSSL:

$ printf "<username>:$(openssl passwd -crypt <password>)\n" >> .htpasswd