@maksimert/symlink-generator

Symlink generator for Maksimers usage in hosting

This tool is responsible for reading a json file containing symlink definitions in a project.

The tool is ran with the command:

npx @maksimert/symlink-generator -releasenum=SOME_NUMBER

or with the -y included (for newer node versions):

npx -y @maksimert/symlink-generator -releasenum=SOME_NUMBER

There is no need to install it to the project package.json etc.

Custom Server Root (dev server etc.)

In the symlinks.json you define one serverRoot, this would be your regular, probably production server root. If you in the same repository also have a pipeline going to another server, another root etc, this script can receive another argument named serverRoot

Example: npx -y @maksimert/symlink-generator -releasenum=SOME_NUMBER -serverRoot="/home/someuser/sites/somesite"

The symlinks.json file

To run this tool, there needs to be a symlinks.json file present in the directory you run the tool from.

This file has support for 5 different "types" of symlinks. The types are mostly there to help with what paths to select.

Server root

Here you define the path on the server that equals to the path of your repository. Usually the directory where you find wp-config.php

If your repository is structured like this: htdocs/wp-content..etc you find the location on the server where you can see the htdocs folder.

This is usually at: /home/USERNAME/sites/someurl.no/

The serverRoot definition should look like this:

"serverRoot": "/home/USERNAME/sites/someurl.no",

Type: plugins

Plugins is defined as the foldername of the plugin you want to be synced. If your repository contains a plugin with foldername "my-cool-woocommerce-plugin" you enter exactly that in the array of plugins:

"plugins": [
  "my-cool-woocommerce-plugin"
],

If you also have a plugin with foldername "my-plugin-is-way-cooler", you add a new line, making the resulting plugins definition look like this:

"plugins": [
  "my-cool-woocommerce-plugin",
  "my-plugin-is-way-cooler"
],

Type: themes

This works in the exact same way as plugins. If you have a theme with the foldername "awesome-theme", the themes config should look like this:

"themes": [
  "awesome-theme"
],

Type languagePlugin

If you have language files for third party plugins, you add them here.

If the language was Norwegian and the plugin textdomain was "wowiwow" the language files probably has these names:

wowiwow-nb_NO.po and wowiwow-nb_NO.mo

The languagePlugins definition should then look like this:

"languagePlugins": [
  "wowiwow-nb_NO.po",
  "wowiwow-nb_NO.mo"
],

Type languageTheme

This is exactly as the languagePlugin definition, the only difference is what language folder we use for symlinking.

Norwegian language and text domain "best-theme" ends up as:

"languageThemes": [
  "best-theme-nb_NO.po",
  "best-theme-nb_NO.mo",
],

Type files

Here is where things change up a bit. We don't help you with the path for files (We will always start at the repository root folder).

Let's say you have the following files that needs to be symlinked:

htdocs/wp-content/best-file-ever.php and somerandomfolder/somerandomfile.php

The definition looks like this:

"files": [
  {
    "subDirectory": "htdocs/wp-content",
    "fileName": "best-file-ever.php"
  },
  {
    "subDirectory": "somerandomfolder",
    "fileName": "somerandomfile.php"
  }
]

It's best to not include a trailing / You should NOT include a starting /

What happens when this runs?

When this script runs, it goes trough the defined plugins, themes, languages and single files.

It appends some base path to the start of every definition, both for the path in the repository and for the path on the server.

Take plugins as an example.

Your repository is structured like this: htdocs/wp-content/plugins/myplugin

The server root is: /home/coolname/sites/somesite.no

The pipeline you're running is number 13

The tool will create the following symlink command:

ln -sfn /home/coolname/sites/somesite.no/releases/13/htdocs/wp-content/plugins/myplugin /home/coolname/sites/somesite.no/htdocs/wp-content/plugins/myplugin

All that text, and all you did was enter: "myplugin" :)