You may need to update a web application’s settings (such as its public path) at a specific time. For example, you might want to:

  • Show a maintenance page at a specific time.
  • Launch a new version of a site during a scheduled event.

While these changes are easy to make manually using the RunCloud dashboard (as detailed in our “How To Temporarily Disable Your Web App or Show a Maintenance Page” guide), doing so across multiple applications or at a precise moment can be difficult – especially when timing is critical or you won’t have reliable access to the dashboard.

This guide shows how to automate these changes using the RunCloud API and the at command on Linux. You’ll learn how to:

  • Update the publicPath setting using curl.
  • Schedule this update for a future time.
  • Extend the process to multiple applications.

Please note that access to the RunCloud API is an exclusive feature available on our Business and Enterprise subscriptions. This is because API keys are generated and managed within a Workspace, which is designed for team collaboration and advanced project management. By centralizing API key creation within a Workspace, we provide greater security, organizational control, and the ability to manage access for your entire team. To use the API and unlock these capabilities, you will need to upgrade your account to a plan that includes Workspaces.

Preparing Your API Request

To interact with the RunCloud API, you will need:

  1. Your RunCloud API Key and Secret: These are used to generate a Bearer Token for authentication. 
  2. Server ID (serverId): The unique identifier for the server hosting your web application.
  3. Web Application ID (webappId): The unique identifier for the specific web application you want to modify.

You can find these IDs within your RunCloud dashboard.

Creating the curl Command

This example uses the curl utility to send a PATCH request and update the publicPath setting. Refer to the official documentation for details on how to update PHP-FPM and nginx settings.The curl command to update the publicPath looks like this:

curl --location -g --request PATCH 'https://manage.runcloud.io/api/v3/servers/RunCloud_SERVER_ID/webapps/RunCloud_WEBAPP_ID/settings/fpmnginx' \
--header 'Authorization: Bearer RunCloud_API_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "publicPath": "/new-public-path"
}'

In the request above, replace the following values:

  • RunCloud_SERVER_ID: Replace this with your server’s actual ID.
  • RunCloud_WEBAPP_ID: Replace this with the actual ID of your web application.
  • RunCloud_API_TOKEN: Replace this with your valid RunCloud API Bearer Token. 
  • "publicPath": "/new-public-path": This is the setting you want to change.
    • To make the website show a maintenance page, you can change publicPath to /maintenance_html_folder, assuming you have a folder named maintenance_html_folder in your web application’s root directory containing an index.html file.
    • To restore the original public path (commonly /public for Laravel or / for standard sites), set it accordingly. Depending on your application setup, you can also use null to remove the custom path.

Using curl with the at Utility

The ‘at’ utility is a command-line tool available on most Linux systems. It allows you to schedule commands to be executed only once at a specific future time, making it ideal for one-off tasks like a scheduled website launch or temporary maintenance.

Advantages of at:

  • One-Time Execution: Unlike cron, at jobs are executed once and then removed from the queue. This eliminates the need for manual cleanup to prevent re-execution.
  • Precise Scheduling: You can specify dates and times in a human-readable format.

Scheduling API Requests with the at Utility

  1. Log in to your server via SSH. This could be the server hosting the application or any other server from which you want to initiate the API call. 

Use the at command followed by the desired time and date:

at 11:59 PM Dec 24
  1. Enter your curl command at the at> prompt (with all placeholders replaced).
    • RunCloud_SERVER_ID: Your specific server’s ID.
    • RunCloud_WEBAPP_ID: Your specific web application’s ID.
    • RunCloud_API_TOKEN: Your RunCloud API Bearer Token.
    • “/maintenance_path”: The desired new public path, for example, /disabled or /launch_version.
curl --location -g --request PATCH 'https://manage.runcloud.io/api/v3/servers/RunCloud_SERVER_ID/webapps/RunCloud_WEBAPP_ID/settings/fpmnginx' --header 'Authorization: Bearer RunCloud_API_TOKEN' --header 'Content-Type: application/json' --data-raw '{"publicPath": "/maintenance_path"}'
  1. Once you have entered the command(s), press CTRL+D to save the job and exit the at prompt. Once submitted, the system will display a confirmation that the job has been scheduled.

You can check your pending at jobs using atq and remove a scheduled job using atrm JOB_NUMBER.

Extending to Multiple Applications or Settings

You can extend this approach to update multiple applications or modify additional settings. For example:

  1. Create a shell script that loops through a list of serverId and webappId pairs.
  2. Run a curl command inside the loop for each application, updating the relevant settings.

If you have any other questions or need help – please feel free to get in touch with our 24/7 support team. We’re here to help!