Running the service
To fully function, the service needs to run two main components:
- An HTTP server
- A background worker
By default, the mas-cli server
command will start both components.
It is possible to only run the HTTP server by setting the --no-worker
option, and run a background worker with the mas-cli worker
command.
Both components are stateless, and can be scaled horizontally by running multiple instances of each.
Runtime requirements
Other than the binary, the service needs a few files to run:
- The templates, referenced by the
templates.path
configuration option - The compiled policy, referenced by the
policy.path
configuration option - The frontend assets, referenced by the
path
option of theassets
resource in thehttp.listeners
configuration section - The frontend manifest file, referenced by tge
templates.assets_manifest
configuration option
Be sure to check the installation instructions for more information on how to get these files, and make sure the configuration file is updated accordingly.
If you are using the docker image, everything is already included in the image at the right place, so in most cases you don't need to do anything.
If you are using the pre-built binaries, those files are shipped alongside them in the share
directory.
The default configuration will look for them from the current working directory, meaning that you don't have to adjust the paths, as long as you are running the service from the parent directory of the share
directory.
Configure the HTTP server
The service can be configured to have multiple HTTP listeners, serving different resources.
See the http.listeners
configuration section for more information.
The service needs to be aware of the public URL it is served on, regardless of the HTTP listeners configuration.
This is done using the http.public_base
configuration option.
By default, the OIDC issuer advertised by the /.well-known/openid-configuration
endpoint will be the same as the public_base
URL, but can be configured to be different.
Tweak the remaining configuration
A few configuration sections might still require some tweaking, including:
telemetry
: to setup metrics, tracing and Sentry crash reportingemail
: to setup email sendingpassword
: to enable/disable password authenticationaccount
: to configure what account management features are enabledupstream_oauth
: to configure upstream OAuth providers
Run the service
Once the configuration is done, the service can be started with the mas-cli server
command:
mas-cli server
It is advised to run the service as a non-root user, using a tool like systemd
to manage the service lifecycle.
Troubleshoot common issues
Once the service is running, it is possible to check its configuration using the mas-cli doctor
command.
This should help diagnose common issues with the service configuration and deployment.