Running¶

If you installed motley_cue using a package manager, you can simply start the service by:

systemctl start motley-cue

The motley_cue API will be available http://localhost:8080.

It is highly recommended to use HTTPS. The nginx site file installed with the package also provides an example configuration for that in the comments (see section on how to manually configure nginx with motley_cue for more details).

You will also need certificates for your server. Probably the simplest way to do that is by using https://letsencrypt.org/.

Development¶

If you installed motley_cue with pip, for quick testing you can simply run it with uvicorn (as user with permissions to add users):

sudo motley_cue_uvicorn

The API will then be available at http://localhost:8080.

Production¶

This section describes how to run motley_cue in production if you installed it with pip. If you used the package, these configuration options are already applied.

To set up the production environment, we recommended using:

gunicorn: manages multiple uvicorn worker processes, monitors and restarts crashed processes
systemd: service management and monitoring
nginx: HTTPS support, buffers slow clients and prevents DoS attacks

The code examples below assume a python virtualenv at /usr/lib/motley-cue, where you have installed motley_cue and its dependencies. Adapt paths if necessary.

Templates for all referred configuration files are provided with either the package or the pip installation.

gunicorn¶

To configure motley_cue to run with gunicorn, you will need two additional configuration files.

gunicorn.conf.py: config file for gunicorn with sane default values.
motley_cue.env: here you can set the environment variables used in the gunicorn config, such as the socket address gunicorn listens on (BIND), log file location or log level.

Recommended locations for these files:

/usr/lib/motley-cue/etc/gunicorn/gunicorn.conf.py
/etc/motley_cue/motley_cue.env

systemd¶

Create the service file to run gunicorn under systemd and place it in /lib/systemd/system/motley-cue.service:

[Unit]
Description=motley_cue with gunicorn service
Before=nginx.service

[Service]
User=root
Group=root
RuntimeDirectory=motley_cue
WorkingDirectory=/usr/lib/motley-cue
EnvironmentFile=/etc/motley_cue/motley_cue.env
ExecStart=/usr/lib/motley-cue/bin/gunicorn motley_cue.api:api -k "uvicorn.workers.UvicornWorker" --config /usr/lib/motley-cue/etc/gunicorn/gunicorn.conf.py
ExecReload=/bin/kill -s HUP $MAINPID

[Install]
WantedBy=multi-user.target

Start the service with:

systemctl start motley-cue

nginx¶

An example site configuration is provided below:

# # if you uncomment this block, make sure that the default site
# # that might come with a clean nginx install is disabled
# # i.e. rm /etc/nginx/sites-enabled/default
# server {
#     listen 80;
#     server_name localhost;
#     return 301 https://$server_name$request_uri;
# }

server {
    listen 8080;
    listen [::]:8080;

    # # if you uncomment this block, make sure you remove the two directives above
    # # also consider uncommenting the server block above for port 80 redirects to 443
    # # alternatively, you could use port 8443 instead of 443, as this port is also
    # # checked by default by the mccli client software.
    # listen 443 ssl;
    # listen [::]:443 ssl;
    # ssl_certificate /etc/ssl/private/nginx.pem;
    # ssl_certificate_key /etc/ssl/private/nginx.key;

    server_name _;
    location / {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;
        # we don't want nginx trying to do something clever with
        # redirects, we set the Host: header above already.
        proxy_redirect off;
        proxy_pass http://unix:/run/motley_cue/motley-cue.sock;
    }
}

Copy it to the appropriate location (e.g. /etc/nginx/sites-enabled/nginx.motley_cue) and reload nginx.

Config files¶

This is the list of the required configuration files, which are usually present when you install motley_cue with a package manager:

Navigation

Related Topics