Defining services
Services are defined in the[services] section of the manifest.
A service needs a command to run to start it.
It can also set vars that apply only to that service,
declare whether it spawns a background process,
control how it is shut down,
and name other services that must start or finish first.
See manifest-toml(1) for
more details on the exact format of the [services] section of the manifest.
An example service definition is shown below:
database that starts a PostgreSQL
database and configures some of its properties through environment variables.
Daemons
Some services cannot be shut down by the default mechanism (sending the spawned process aSIGTERM).
Most often this is because the spawned process itself spawns another process (typically a daemon) and then terminates. In this case you need to provide your own command for shutting down the service. You do this by setting is-daemon = true for the service and providing a shutdown.command. Below is an example that uses pg_ctl (the daemon-spawning launcher) instead of exec postgres, which launches postgres in the foreground. It demonstrates the is-daemon = true + shutdown.command pattern for programs that background themselves. Together these fields allow the service manager to shut down services that background themselves.
Shutdown behavior
By default the service manager stops a service by sendingSIGTERM to the
service’s process and waiting for it to exit.
It does not escalate to SIGKILL on its own,
so a process that ignores SIGTERM, for example a server paused in a
debugger, keeps running after flox services stop
and shows as Terminating in flox services status.
Set shutdown.timeout-seconds to give the service a deadline.
flox services stop then waits that many seconds for the process to exit
and sends SIGKILL if it is still running:
shutdown.signal to send a signal other than SIGTERM,
for example 2 for SIGINT.
Signal numbers above 15 mean different things on Linux and macOS,
so stay within 1-15 in an environment shared across systems.
You can define a shutdown.command for any service,
including services that do not run as daemons.
The service manager runs the command instead of sending a signal,
so shutdown.signal cannot be combined with it.
The command gets 10 seconds to finish,
or shutdown.timeout-seconds if set,
after which the service manager sends SIGKILL to the process it is
tracking.
Some shutdown commands need longer than 10 seconds,
for example a command that stops a collection of containers:
shutdown.timeout-seconds must be greater than zero.
Both
shutdown.timeout-seconds and shutdown.signal require manifest
schema-version = "1.16.0" or later.
Flox updates the schema version when you save a manifest that uses them,
after which versions of Flox older than 1.16.0 can no longer read the
environment.Start order
By default all services start at once. Usedepends-on to hold a service back until another service reaches a
given state.
Each entry names another service and a condition:
process_started: the other service’s process has started.process_completed: the other service’s process has exited, with any status.process_completed_successfully: the other service’s process has exited with status0.
web only after migrations has finished successfully:
--start-services or auto-start,
or with flox services start and no service names.
While a service waits for its dependencies,
flox services status shows it as Disabled.
Starting a service by name starts only that service.
A dependency that is not already running is neither started nor waited for.
Flox does not yet support health checks,
so a dependency can wait for a process to start or exit,
but not for it to become ready to serve requests.
A dependency on a service that is excluded from the current system by
systems is ignored on that system.
Like the shutdown fields above,
depends-on requires manifest schema-version = "1.16.0" or later.
Starting services
Services can be started automatically when you activate your environment via theflox activate --start-services command
(or via the shorter flox activate -s).
This will start services as part of activating your environment.
When activating your environment from multiple shells you only need to start
the services once.
Since your services are just processes running on your machine,
they will be visible to any other activations.
Activating your environment without the --start-services flag will not start
the services.
If you activate your environment without services and then later decide that
you want to start them, that is done via the flox services start command.
When called without any arguments this command will start all services listed
in the manifest.
You can also specify individual service names,
in which case only those services will be started.
If you accidentally provide a service name that doesn’t exist,
you’ll get an error and no services will be started.
If a service is already running,
you’ll see a warning but the command will otherwise succeed.
Stopping services
Services are automatically stopped when the last running activation of the environment terminates. This means that if youflox activate -s in a single shell,
the services will be shut down automatically when you exit that shell.
Similarly, if you flox activate -s in one shell, then flox activate in two
more shells,
the services won’t be shut down until all three of those activations have
terminated.
You can stop services yourself via the flox services stop command.
You can also specify individual service names,
in which case only those services will be stopped.
If you accidentally provide a service name that doesn’t exist,
you’ll get an error and no services will be stopped.
If a service is already stopped,
you’ll see a warning but the command will otherwise succeed.
Restarting services
Services can be restarted via theflox services restart command.
You can also specify individual service names,
in which case only those services will be restarted.
If you accidentally provide a service name that doesn’t exist,
you’ll get an error and no services will be restarted.
When services are already running,
flox services restart restarts each service in turn and does not apply
depends-on ordering.
To bring a set of dependent services back up in order,
run flox services stop followed by flox services start.
Handling environment edits
While working in your environment that has running services, you may discover that you need to edit a service definition or some other part of the environment. In this scenario you would callflox edit like usual,
but now the manifest is out of sync with both the current activation of your
environment and the running services.
After making the edit you’ll see a warning about needing to reactivate your
environment in order to apply the changes to your shell,
but if you just want to apply the changes to your services
(say you only modified a service definition)
you can do so without needing to reactivate your environment.
There are two ways to accomplish this:
flox services restartflox services stopfollowed byflox services start
flox services stop in the second case is only necessary if any services
are currently running.
Checking on services
You can see the status of your services with theflox services status
command.
This will display the name of the service, the PID, and its status.
An example is shown below:
flox services logs command.
This command operates in two modes:
- all services with
--follow - single service with either
--followor--tail
--follow flag must be provided,
in which case logs for all running services will be displayed in real time.
If a single service name is provided then the logs for that service will be
displayed.
Logs for the service manager itself are stored as services.*.log files in the
.flox/log directory of your environment.