Installation scripts for SURF ResearchCloud catalog components
View the Project on GitHub UtrechtUniversity/researchcloud-items
This role can be used to generate nginx location blocks that will be served by the nginx webserver running on a workspace. This way, you can serve pages to the internet (reachable at the workspace’s FQDN), create a reverse proxy that exposes an application running on localhost, easily add authentication, and anything else you can do with nginx! In particular, it allows you to:
The role does not install nginx, and instead assumes that it is installed by the standard SRC-Nginx component.
Please see the examples below to understand the syntax for location block configuration, including for SRAM authentication.
/etc/nginx/app-location-conf.d/
that define reverse proxieshtpasswd
files for HTTP basic auth.nginx_location_locations
: Required. List of dict objects defining the locations. Examples:# first location
- name: root # required
location: / # required
proxy_pass: http://localhost:8000/ # the webapp running on localhost -- not required! you can instead use e.g. 'alias' as well.
auth: noauth # Special key, see the other location blocks below for auth examples.
include_reverse_proxy_defaults: false # Special key. Set to true to include some sane default proxy configurations regarding timeouts etc. See the [nginx_reverse_proxy](/researchcloud-items/roles/nginx_reverse_proxy.html) role. Default: false
# The options below are example of common nginx options
# Any "key: value" pair you add will be translated to a "key value;" directive in the nginx config
client_max_body_size: 10G
send_timeout: 300
# You can also use nested dicts
proxy_set_header:
header1: foo
header2: bar
# will yield:
# proxy_set_header header1 foo;
# proxy_set_header header2 bar;
add_header: # headers that nginx will add to the response
foo: bar
bar: foo
# will yield:
# add_header header1 foo;
# add_header header2 bar;
#since Jinja dictionaries are unordered, the order in which directives are rendered cannot be guaranteed.
# if order needs to be preserved, you can use a list, with each list item an arbitrary dict. For example:
_foo: # starting key with a _ means they key will not be rendered as part of the directive
- foo_enabled: true
- foo_setting: bar
# ...will render foo_enabled true; foo_setting bar;
- name: basicauthlocation # second location, with http basic auth
location: /test_basicauth/ # uri
auth: basic
htpasswd: myfile1 # which of the htpasswd files to use for auth, see the nginx_location_auth_info variable
- name: sramauthlocation # third location, with SRAM auth
location: /test_sramauth
auth: sram
auth_sram_header: REMOTE_USER # Special key. Optionally specify which header should be filled with the name of the externally authenticated user. Default: REMOTE_USER
- name: api # fourth location, without auth
location: /test_sramauth/api
auth: noauth # explicitly disables auth for the location -- useful to make exceptions for sublocations of otherwise protected locations
- name: default_basic_auth_credentials # fifth location, http basic auth with default credentials
location: /test_default_credentials
auth: basic
# If you set a htpasswd file that is not defined in the nginx_location_auth_info variable, the file will be created with the default credentials (see below):
htpasswd: not_defined_in_nginx_location_auth_info
nginx_location_htpasswd_path
: String. Where to store and look for htpasswd
files. Default: /etc/nginx/passwd
.nginx_location_auth_info
: Optional. List of dict objects defining htpasswd
files for use with HTTP basic auth. These files will be generated using the provided username/password combinations. Example:- name: myfile1 # will be stored under <htpasswd_location>/myfile1
username: tester
password: letmein
- name: myfile1
username: tester2
password: letmein
When you have defined a location with a htpasswd
attribute in the nginx_location_locations
, but this htpasswd
file does not occur in the nginx_location_auth_info
parameter, that htpasswd will be created with the default credentials:
nginx_location_default_username
: String. Standard username to add to an httaccess file if none is explicitly provided (see nginx_location_auth_info
). Default: ''
.nginx_location_default_password
: String. Standard password to add to an httaccess file if none is explicitly provided (see nginx_location_auth_info
). Default: ''
.2024-2025 Written by Dawa Ometto (Utrecht University)