The Symlink (Config) feature in RunCloud’s atomic deployment is a powerful tool designed to handle sensitive configuration files that are not tracked in version control systems due to their sensitive nature.

This functionality is particularly useful for adding these files automatically during the deployment of a new version of your site.

Additionally, it enables the management of different configuration files for various branches of your application, such as production and development environments.

Prerequisites

Before configuring this feature, you must first deploy a web application using Git.

Next, you need to upgrade your application within the RunCloud Dashboard to enable atomic deployment, which ensures that your deployments are handled atomically – preventing any downtime during the deployment process.

To create a Symlink for your web application, navigate to the ‘Atomic Deployment’ page within the RunCloud Dashboard using the left menu, and then select your desired application.

Next, click on the “Symlink” tab on the left sidebar.

On this screen, you will be able to see all your existing Symlinks.

To create a new link, click on the “Add New Symlink” on the right side of the screen.

On the next screen, you can create a new symlink by selecting ‘Config’ as the symlink type.

In the ‘Link From’ field, enter a name for your configuration file – this could be something like production.env or my_test_file.

In the ‘Link To’ field, specify the name of the file that your application or CMS expects to find in the root directory of your app folder. For instance, Laravel looks for .env, while WordPress looks for wp-config.php.

After specifying the file name, click on the checkbox next to the application for which you want to apply this configuration.

Finalizing Configuration Content

Next, you will be prompted to enter a secret key to secure your config file. Enter a secure and memorable passphrase, as it will be use to secure access, and allows future edits to the configuration file’s contents.

After adding your passphrase, the final step in the symlink creation process is to enter the contents of your configuration file. The information you provide here will be saved within the configuration file, and automatically included in each new deployment.

Saving and Synchronization

Once you have entered all necessary content, click the ‘Save and Sync’ button at the bottom of your screen to add this file to your server. This action will save your configurations and prepare them for synchronization with future deployments.

After saving the configuration, the Symlink should be accessible almost immediately but it might take longer depending upon the performance and the load on your server.

If the Symlink is not available immediately, you can deploy a new version of your app, this will re-build the app and add Symlink. To launch a new deployment, you can return to your Git repository and make a push – this could be as simple as updating your README file.

Upon pushing these changes, RunCloud will automatically deploy a new version of your site, with the correct configuration file included.

If you prefer not to push changes at this time, you have the option to force a deployment directly from the ‘Atomic Deployment’ tab within RunCloud. This method allows you to rebuild your existing application with the new configuration without making any changes to your repository.

Editing Linked Files

After you have deployed the Symlink, you can view it in the RunCloud File Manager. If you edit this file using RunCloud’s file manager, then the original config file will be updated directly, i.e. – these changes will persist across all versions of your app even after it has been re-deployed.