Run background processes for a site

A web request lasts a fraction of a second, but plenty of things in an application need to run all the time: a WebSocket server, a Node worker, a message consumer, a Python script, a custom artisan command that listens for events. SrvYard calls these background processes. Each one is a Supervisor program that starts with the server, runs as the site's Linux user and is started again if it stops.

This article is about the Processes tab of a site. Queue workers use the same machinery with a friendlier form and are covered in Run queue workers and the Laravel scheduler. The server-wide list of the same kind of programs is described in Keep long-running processes alive with daemons.

Before you begin#

• A deployed site. SrvYard refuses to add a process before the first deployment: "Deploy the site first: processes run from the deployed application."
• A command that stays in the foreground. Supervisor expects the program not to detach. A command that starts a daemon and exits looks like a crash and is restarted over and over. Use the foreground option of the tool (for example --no-daemon) if it has one.
• Permission to manage queues. The same permission covers every process on the tab.
• Know your folder. Commands run in the site's application folder, which for a zero-downtime site is the current link, so a deployment moves the process to the new release when you restart it.

1. Read the Processes tab#

Open the site and choose Processes.

1. The row. Name, the command underneath, the number of copies and the status. The process in the screenshot was created by SrvYard for a Next.js site: it runs npm run start on port 3000 and is restarted automatically after each deployment.

Use Search processes... to find one by name or command. Status filters the table.

The statuses are:

2. Add a custom process#

Press Add background process and choose the Custom tab.

1. Custom. Choose it instead of Queue worker. Name (optional) at the top works for both.
2. Command. One line, up to 1,000 characters, that runs continuously: "If it exits, it is restarted." Use full paths or commands on the site's PATH. The site's PHP is first on the path, so php is the site's version.
3. Working directory. Under Supervisor configuration, press Edit to show it. It defaults to the site's application folder and must stay inside the site folder, with no ...
4. Number of processes. Copies that run side by side, from 1 to 50.
5. Graceful shutdown (s). How many seconds Supervisor waits after the stop signal before it kills the process, from 1 to 86,400 (the default is 15). Give a worker that finishes jobs a longer time.

Press Create background process. The row appears as Creating and then Running. If it goes to Failed, open the log (step 3).

SrvYard fixes some settings so every process behaves the same way: it runs as the site user, starts with the server, restarts when it exits, counts as started after one second and receives TERM as the stop signal. The Name is lowercase letters, digits, - and _, up to 50 characters, unique on the server. Leave it empty and SrvYard names the process after the site.

3. Start, stop, restart and read the log#

1. Restart. Use it after a deployment for a process that is not restarted automatically. Start and Stop are next to it. The toast says "Starting the process...", "Stopping the process..." or "Restarting the process...".
2. View logs. Opens the program's log file with Auto refresh and Refresh. The path is shown above the text. By default you see the last 200 lines, which is what the program wrote to its log.
3. Edit. Change the command, working directory, copies or shutdown time. Not available while a change is in progress.
4. Delete. Removes the process.

A process owned by a Laravel feature (Horizon, Octane, Reverb, Inertia SSR) or by a Next.js or Nuxt.js site can still be started, stopped and read here. The Laravel ones cannot be edited or deleted from this tab: "This process belongs to a Laravel feature. Change it from the Laravel panel on the site overview."

1. Delete process. The process is stopped and its Supervisor configuration and log are removed from the server. Nothing in your code changes.

4. Processes and deployments#

• Zero-downtime sites. A process started from the current link keeps running the release it started with, even after current points at a new one. Restart it with the Restart button after the deployment, or have the application exit on its own when it notices a new release so Supervisor starts it again.
• Next.js and Nuxt.js. SrvYard restarts the application process itself when a release goes live. A failure to restart is written to the deployment log as "The application process could not be restarted" and does not fail the deployment.
• Queue workers. $RESTART_QUEUES() in the default deploy script makes them exit so Supervisor starts new ones.

5. Processes found on an adopted site#

When you adopt a site that is already on the server, the Supervisor programs of the old setup show up on the same table. SrvYard marks them as external: you can start, stop, restart and read their logs, and Take over converts one into a process SrvYard manages. A program that writes no log file of its own has no log to show.

Troubleshooting#

• The process is Running but nothing happens. The command may have started a background job and exited, or the application listens on a port nobody proxies to. Read View logs and check the command stays in the foreground.
• It restarts constantly. The command exits straight away. Run it by hand from the Commands tab to see why, for example a missing environment variable.
• "The working directory must be inside the site folder". Use a path under the site's folder, without ...
• "The command must be a single line." Move multi-line logic into a script file and call it.
• The log says "This program does not write a log file of its own". It is an external program from the old setup; read its output where that setup writes it.
• The status stays Unknown. SrvYard cannot reach Supervisor on the server. Check the server's state and the Services tab, then restart the process.
• Old code keeps running after a deployment. The process started from a previous release. Restart it.

Related#

• Run queue workers and the Laravel scheduler: the queue worker form and the cron job.
• Keep long-running processes alive with daemons: the server-wide view.
• The Laravel panel: processes that belong to Laravel features.
• Read site logs and run commands: debug a command before you make it a process.