When deploying websites, some configuration files that contain sensitive information, such as database passwords, are not tracked in version control systems due to their sensitive nature.
Symlink allows you to add these files automatically to your website when a new version is deployed.
What is Symlink in Atomic Deployment?
A symbolic link is a pointer that refers to another file or directory without copying or moving it. This can help you simplify your file structure, share files between web applications, and avoid duplication.
Additionally, it enables the management of different configuration files for various branches of your application, such as production and development environments.
RunCloud supports two types of symlinks: Config and Directory. Let’s see what each one does!
Config (file) Symlink
Config Symlink allows you to dynamically add your configuration files, such as .env, .htaccess, etc., to your web applications. Configuration files are usually not tracked by Git, as they may contain sensitive information or vary depending on the environment. This allows you to store your configuration files in a secure and encrypted format and then link them to your web applications using Symlink.
When you create a config file, you need to choose which web application will receive this configuration. Most of the time, you need to choose all web applications unless each uses different configurations.
For example, with Laravel and Symfony you have .env config files. Let’s say you name it application-env. Inside the ‘link from‘ field, you should add application-env and .env in the ‘link to‘ field.
The name of the file inside the configs folder doesn’t matter, but in the link to the field, you should name it with the correct name for your application. If you need more help, read our step-by-step instructions on how to configure Symlink on RunCloud.
Note: The config file you create will be encrypted and stored in the configs folder on your server. You must provide the secret key when you want to install or update the config file. If you forget the secret key, you will have to delete the config file and create a new one. Deleting the config file will not affect your web application folder.
Directory Symlink
Directory Symlink lets you link to your uploaded files or folders, such as images, videos, documents, etc. Uploaded files or folders are usually not tracked by Git, as they may change frequently or take up too much space. You can store your uploaded files or folders in a separate folder called ‘storage‘, then link them to your web applications using Symlink.
Note: The folder you link to should be empty in your web application folder, otherwise it will be replaced by the Symlink.
Creating Symlinks in RunCloud
Let’s see how easy it is to add a Symlink from the RunCloud dashboard.
Prerequisites
Before configuring this feature, you must deploy a web application using Git.
Next, you need to upgrade your application within the RunCloud Dashboard to enable atomic deployment. Atomic deployment ensures that your deployments are handled atomically, preventing downtime during the deployment process.
Linking Config Files
To create a Symlink for your web application, use the left menu to navigate to the ‘Atomic Deployment’ page within the RunCloud Dashboard and select your desired application.
Next, click on the “Symlink” tab on the left sidebar.
On this screen, you will see all your existing Symlinks.
To create a new link, click “Add New Symlink” on the right side of the screen.
You can create a new symlink on the next screen 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 file name 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 to 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 used to secure access, and allow 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 on 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 rebuild 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 can 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 changing 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.
