Using Enmuster Using EnmusterEnmuster is a cross-platform tool for deploying websites and web apps.
Once set up, it's a one click action on the big orange button
to deploy changes to a project. A change means
a file whose date or size differs between your local and remote copies.
Warning: Enmuster's purpose is to replace and delete files on your server and possibly execute some of them. If that doesn't work properly, you could lose files. Make sure you have a backup. If the authentication doesn't work as intended, nasty people could get access to your server. Use at your own risk.
The intention is that you have one or more local copies in a folder/directory and you need to transfer your changes to the web server, your target site. The local copy could be a working copy in which you have been testing. More likely your working copy is managed in some kind of source control system like Subversion or Git and you have a second copy to which you check out for the production and/or test (staging) web site.
Updating can be done over HTTPS or HTTP (but still encrypting the content), or over SSH. It can also do any of those indirectly through a SSH tunnel. With HTTP(S) it can communicate with the server either as part of the site which is being updated, or, better, a separate domain (e.g. a sub-domain of the site being updated) hosted on the same server. So in the worst case, if the only access to your server is a single domain on http, you can still use Enmuster, but if you have shell or root access to your server you have more options.
Getting Started • Security • Projects • Folders • Exclusions • Deploy via URLs • Live sites • Via tunnel • Revision numbering • Maintenance mode • Upgrading • Settings • Known bugs • Credits
There are other strategies, but I've never found any to be completely satisfactory. There are other synchronisation tools too, but again, most of them don't really work as I want them to.
For example, you could check out from source control directly on the server. However, this means the files which manage the source control are present on the live site; and when working in groups, it also relies on everyone having compatible versions of source control tools.
For a long time I've used a tool called WebDrive on Windows, which represents a remote server as a local drive letter. However, while it works, it doesn't sit well with Subversion and its Windows client, TortoiseSVN, because it constantly uploads and downloads its database file, and occasionally this gets corrupted (bad news).
Ansible is a good option for large scale deployment, but it is overkill for just one or two instances of a web site. You end up effectively writing "scripts" in their YAML-based language. The version with a UI is beyond the financial reach of small projects.
The worst strategy is, of course, noting which files have changed and copying them manually using programs like WinSCP or FileZilla.
Enmuster has two components, client and server. The server comprises just one PHP file (PHP in order to support the widest possible range of servers), which you can obtain using the button in the settings page in the client. Instructions for installing this are in the file. It requires a Linux server, probably running Apache, with openssl installed. You will need to make a directory on your server, which we'll call the Enmuster Data Directory, which the web server can write to, and in which you put your public key and links to the directories that are to be updated. The server file has a link to the Enmuster Data Directory at the top.
Once set up, the whole project can be transferred on first deployment: the receiving directory on the server just needs to be empty to start with.
The client lets you say what files to deploy and where. You can also
) without actually
making any changes on the server,
),
which often helps when first setting up,Enmuster stores multiple projects. Projects are independent of each other, representing entirely separate web sites.
Each project identifies one or more folders on your computer whose contents (that are new or have changed) will be copied.
Each folder can then be copied to one or more targets via http[s] requests to URLs of Enmuster Servers which you set up. These can be on different server computers, or virtual servers all on the same one. However it is also possible to use the same Enmuster Server to service multiple copies on the server computer (using the fragment notation in the URL, that is a part after a hash symbol)
Each URL can be accessed directly, or via a SSH tunnel. Tunnels make access possible to servers behind gateway machines.
URLs can also be marked as "live sites". You have to turn deployment for live sites on each time you want it to avoid accidental premature deployment.
When you press the deploy button ()
each URL of each folder
you have added to the project is deployed
in turn, unless the URL, folder or project is temporarily turned
off (
).
If the deployment button looks like this:
then the deployment will only be tested. Everything, including
file uploads, will be done as normal, but the server will not
actually ad, remove or update any files.
Here's what happens for each URL/folder combination:
The changes made are listed.
If files are found on the server which post-date those in the local copy, the deployment does not continue. This is because it is assumed someone else has made changes, and therefore you would lose those changes if you were to upload your own.
When updating over HTTP or HTTPS (rather than SSH), your server needs to be able to accommodate the size of the uploads. Most PHP uploads, for example, are limited to 2MB per file, and this may not be enough. There are two settings to change, either in your php.ini file or Apache .htaccess file if your server configuration allows it. These are upload_max_filesize (the limit for any one file) and post_max_size (the limit for all the files in total, for which the default is usually 8MB). You should be able to set the limit just for the Enmuster site or Enmuster part within your larger site in a .htaccess file as follows, say:
php_value post_max_size 200M
php_value upload_max_filesize 20M
However, some installations don't allow this, and in others where PHP is run as a CGI module rather than built in to Apache, this doesn't work. In that case you need to locate the lines in your php.ini file on the server and update the values there instead. If you can't do either, you need to complain to your provider and/or use SSH to do the upload instead.
When the synchronisation button () for a
particular URL is pressed, local files in the relevant folder
which are the same as those on the server identified by the URL
have earlier time stamps set to those on the server. Files which
are different, or missing on the server, will be identified but
not changed. "The same" means the files are the same size and have
the same content as determined by their md5 signatures.
This is often helpful when first setting up from an existing collection of files because thereafter deployment is based on similar sizes and times as described above.
It is also useful to determine which files do actually differ whatever their time stamps happen to be, again typically when first setting up.
Notice this is done for a particular URL as, if there is more than one, files at each would have their own time stamps. Generally you'll want to set the times to those latest, though sometimes there is a mixture of times, so some manual sorting out will be required.
Enmuster enables arbitrary files to be uploaded to your web server, over HTTP or HTTPS, and some of them to be executed as scripts! But only by you, of course. In theory. Because of that, security is important, so that unauthorized visitors cannot also upload and execute files and therefore do pretty much anything they like.
These are the same operations you would do manually if updating your web site, but you need to know what is happening to ensure that there is no malicious access to your server.
There are three aspects to this:
Privacy is easily managed using HTTPS or SSH, both of which use encryption by definition. However, it isn't always practical to use HTTPS or SSH instead of HTTP. In this case, data is encrypted explicitly by Enmuster for transfer.
If you use self-signed certificates with HTTPS, see note under URLs. However, certificates are now available free from Let's Encrypt, if your server environment or provider allows you to install them.
Authentication between client and server is managed using an
openssl key pair. Your Enmuster server needs openssl to
be installed for this to work. The Enmuster client generates
corresponding public and private keys and keeps the private key to
itself on your computer (you can make a new key-pair on the
Settings page 
).
Put the public key (which is offered to you each time you change or add a URL and from the Settings page) into the Enmuster Data Directory (which you create when setting up the Enmuster Server) in a file named according to your client. This means only a client with a private key matching a public key manually uploaded to the server is allowed to establish a connection.
For example, if your client name is Jerry and your Enmuster Data Directory is at /home/bj/enmusterdata, then you need to copy your public key to /home/bj/enmusterdata/Jerry.pem. Your collaborator Ben can also deploy their copy if they install their public key at /home/bj/enmusterdata/Ben.pem.
The private key is stored in the app's local storage: typically this is a file in C:\Users\username\AppData\Local\enmuster on Windows. Keep it safe. It provides the same level of access to your server as logging in or using (S)FTP etc.
Furthermore, if you upload over SSH rather than HTTP(S), you are logging in to your server using your own credentials. You supply the username in the URL and either the password also, or, better, rely on a SSH Agent (Pageant on Windows).
While most files uploaded will simply replace or augment the ordinary files already in your target web site, and therefore have the same security considerations as any website development, the files uploaded for turning maintenance mode on and off, and for upgrades are special. You do not want these to be accessible by the general visitor, so must not be placed in a directory which is served over HTTP.
There will be other files you don't want to expose to public gaze too, as a matter of course. It should be safe to put these two files among them, or in a utilities directory or some such.
Enmuster also sometimes deletes files from the server! Actually, it doesn't really delete them, it puts them in a backup directory in the Enmuster Data Directory named with the date. Nevertheless they get removed from their previous place.
This happens when the corresponding file is removed at your end, so Enmuster removes it to match. However, if you have a place on the server where, for example, you put files uploaded by users, then these won't exist locally and would be subject to removal. Therefore, it's really important to identify these and make exceptions for the folders where they will go. Other examples are log files, and config files with specific names but whose contents differ from one copy of a site to another.
Projects are listed by name at the top of the page. Click one of these buttons to select it and display its details underneath. You can also re-order this list by draggging the buttons.
The enmuster symbol to the left of the project name in the main
part of the window shows green 
if the
project will be entirely deployed when the deploy button
is pressed; yellow 
if only
some of its folders or URLs will be deployed to or there are some
folders without URLs at all; and red if the
project's deployment is turned off altogether. To turn
off deployment temporarily, click this button; click it
again to turn back on.
When a new project is created, it is set to do test deployments, indicated by the
symbol.
at the end of the list of projects, and
fill in the rest of the details underneath
. When testing, the deployment button looks like
this: , and when live looks like this:
and then
confirm. This has no effect on the server or your local files - it
doesn't delete any files! It just removes the project definition
from the Enmuster client.
alongside the project name. This
saves the project definition to a JSON
file. button near the top of the page.Note that when you export a project which uses tunnels the credentials you use to access those tunnels are removed. If a colleague wants to use the project like this, they must supply their own credentials. Also if a colleague imports a project, it is unlikely their folders will be in the same place as yours, so they will then need to be replaced - see below. The absence of a folder is indicated prominently!
Each project comprises one or more folders (directories) on
your computer. When you deploy () or test () a project, each folder is scanned for changes
and these (excluding exceptions) are transmitted to each of the
URLs associated with the folder.
Each folder then comprises a number of sections which control
how the deployment happens. You can hide or show
the sections by pressing the arrow 
or 
to the left of the first section under the
enmuster button.
The sections manage: excluding specific folders or files and excluding files which match a pattern; URLs to deploy the folder to, possibly via a tunnel; revision numbering; maintenance mode; and programmed upgrades.
alongside the folder name, and confirm.),
press the enmuster button to the left of its path. This shows
green when the folder will be deployed to
all its URLs, yellow if some of the URLs
are suspended or there are none and red if
the folder is itself suspended. To turn back on, click the
button again.)You can either ignore specific files or folders within a folder hierarchy or files or folders anywhere in the hierarchy whose names match a simple pattern. The first two sections under the folder name manage this.
When a folder is deployed, changes to it are mirrored on the server. This includes removing files: if you delete or rename an item locally, the same item will be removed from the server. When an item is removed on the server it is backed up in a directory named by date in the Enmuster Data Directory.
However, some directories on the server will probably be used to store the state of the web app: files the users have uploaded, or transient files. By definition, these won't appear in your local copy so would normally be subject to removal. Therefore you need to add an exception for the folder(s) which will contain these files. You will need a (possibly empty) version of the folder in your local copy to exclude it. If that's a test version, it will naturally exist anyway.
Other examples include configuration files which may be present at both ends but are unique to each site and shouldn't be overwritten with a local version. Exclude these too.
The names of excluded items are stored relative to the local folder, so if you move it, your exclusions still work.
Excluded items are completely ignored at both ends. If a folder is excluded, we don't look at what's in it at either end when looking for changes.
next to the item, and confirm. This has no effect
on the item itself. However bear in mind that on next
deployment, this may cause that item to be deleted or
overwritten with a local copy (see above).You can also ignore any files or folders whose names match a simple pattern. Such files or folders (and their contents) will be ignored wherever they appear in the folder hierarchy.
Examples include files left around by editors (such as Emacs' backup and editing in progress files) and folders used by source control systems (Subversion uses a .svn directory to store its database).
The patterns are very simple; they are not full regular expressions. An asterisk is the only special character: a wildcard meaning any sequence of characters. A comma is, however, used to separate the patterns so commas in patterns are not recognised. A period is just like any other character (those familiar with regexps will know that for those, ulike Enmuster, a period means any single character). Question marks are also not treated specially.
The whole name must match for it to be ignored (so if you have b*d for example, abcd or bcde won't be excluded.
A selection of commonly encountered files to ignore is provided when you add a folder. They will be ignored at both ends of the update and need not exist at either end.
at the end of the block labelled deploy this
folder via these URLs. Then paste or type the URL into the
box provided.
alongside, and confirm.
./ to the left of
the URL. Only those shown green will be included in a
deployment.
. The button turns orange 
: press again to turn off. of file times.The URL may contain some less familiar components. In its full glory it may look something like this:
https://username:password@enmuster.example.com:1234/enmuster#live
The URL will definitely include the protocol, http, https or ssh. It might include a port number after the domain name part, and, less likely, username and password if it is set up to use ssh, basic auth or digest auth (though basic or digest auth is not rerally needed as authentication is managed by Enmuster's key-pair). It may also have a path part if it is not a site in its own right (for ssh this will be the location of the script relative to your home directory). If deploying to several instances of a site on the same server, it will have a fragment, that is a hash part.
When you add a URL, the site it refers to is checked, so it must already have been set up. It also offers you a public key to put on the server to permit your deployments: see authentication above. If you are using the same server for multiple deployments you only need to do this once.
Each folder is deployed over HTTP, HTTPS or SSH to an Enmuster
Server. The server is very simple: it's just one file, and you can
download it by pressing the button for this on the Settings page
(). Instructions for installation are in
the file.
Ideally, the Enmuster Server should run as its own web site, i.e. with its own URL. However, it can be in subfolder of the Target Site if you must, and this is undoubtedly simpler (it doesn't require setting up a new virtual server in Apache).
When not using SSH, ideally the Enmuster Server should be an encrypted web site, that is HTTPS. However, it can be HTML if you must, and the data transferred will be independently encrypted.
Ideally, you would put the Enmuster HTTP Server on its own port (it should be private). This will avoid problems where HTTPS connections cannot share virtual servers on the same port. However, the client is up-to-date so Server Name Indication (SNI) will also work. Of course, you cannot do this if it is run as part of your target site.
If you can only use HTTP, you could also consider only allowing access from a client machine you have access to (Apache's Allow from address directive, where address is localhost.
If you don't have HTTPS but you can log in to your server manually using ssh, you can set up Enmuster to do the same automatically. As indicated above, use a URL like this:
ssh://Jerry@www.icecream.com/enmuster
If your ssh server is running on a different port, include that in the usual way. You can also include your login password here if you must. So you might potentially have:
ssh://Jerry:mypassword@www.icecream.com:1234/enmuster
However, it is better (whether Enmuster or manual login) to set up a key pair to do this, where the private key is itself protected with a passphrase.
If you're on Windows, chances are you are logging in to your server over ssh using PuTTY, the de-facto ssh client. You generate keys using PuTTY's companion program PuTTYGen, put the public key it gives you in .ssh/authorized_keys on your server, and tell PuTTY to login using its companion program, Pageant, to authenticate the key by ticking the box "Attempt authentication using Pageant" in the Connections - SSH - Auth panel in puTTY. Similarly on Unix (including Mac) ssh can talk to ssh-agent.
Enmuster does the same as puTTY: it talks to Pageant or ssh-agent to obtain its authorization to log into the server using the same Pageant/ssh-agent key-pair as for manual logins. So if you can log in to your server manually using PuTTY or ssh in this way, Enmuster can do so also, and it needs no further passwords. Pageant is the default, identified by the word 'pageant' in the authentication agent box in settings; if using ssh-agent, put the path to the Unix socket that it provides in the box.
For ssh, the path part of the URL indicates where (relative to your home directory) the PHP script to manage the updates is located (the same script as for HTTP(S)). This can either be the path of the script or the path of a directory in which index.php is located. For SSH, as this directory is not exposed by the web server, you can use the same directory as your Enmuster Data Directory if you want.
There is no longer any reason to use self-signed certificates. Let's Encrypt now provides proper certificates free of charge.
However, if you must use a self-signed certificate with HTTPS
for your an Enmuster Server, then your certificate will normally
be checked just like a browser would, and would reject it. You
need to allow connection using a URL which has a self-signed
certificate to override these checks. Press the padlock button
alongside the URL indicating a secure connection
() so that it shows yellow
instead: 
(click again to turn
full security checks back on).
In principle, the identity of the server cannot be assured with a self-signed certificate. However, in this case, your identifty is checked on the server by your public key, so a "man-in-the-middle" attack would not succeed.
When Enmuster makes its requests to a URL, it uses the project name to locate the files on the server which are to be updated. A link should be placed in the Enmuster Data Directory with the same name as the project referencing the directory to modify. (It can also be a file containing only the path name of the folder).
However, the same Enmuster Server can be used to update more than on instance of the target site. In this case, choose a name for each instance. Instead of a link, make a directory with the name of the project. In that directory put links with names of each instance referencing the relevant directories (or files containing only their paths). At the client end, quote the instance name as the fragment of the URL, that is, the part of the URL after a hash symbol.
For example, say you have two sets of files which should be updated on your server, in directories called /home/me/vanilla and /home/me/chocolate. Let's also assume your Enmuster Data Directory is /home/bj/enmusterdata, your project is called icecream and you've put your Enmuster Server on port 3000 at https://enmuster.icecream.com.
Therefore, on the server, do:
mkdir /home/bj/enmusterdata/icecream ln -s /home/bj/vanilla /home/bj/enmusterdata/icecream/vanilla ln -s /home/bj/chocolate /home/bj/enmusterdata/icecream/chocolate
And on the client, add two URLs:
https://enmuster.icecream.com:3000/#vanilla https://enmuster.icecream.com:3000/#chocolate
Each URL can be marked as a "live site"
using alongside the URL. The button is
shown in orange for live sites. A live
site is one that is in public use (as opposed to a test or staging
version), one which you would not want to update by accident.
When a site is marked live, deployment is turned off for that
URL. To deploy you have to explicitly turn deployment on by
clicking to the left of the URL (it turns
green). When a deployment is completed successfully (i.e. not
counting trial deployments or those which end with errors),
deployment is turned off again automatically. Live sites are
updated more rarely than test or development sites, and this
feature guards against forgetting to turn off deployment
afterwards, which would lead to accidental updates next time you
intended just to update a staging site.
You can turn deployment on and off for all live sites at once
using the two buttons 
and 
respectively, next to the project
name.
Normally, your HTTP(s) or SSH connection specified by the URL is direct from your computer to a specific port on the server (often 80, 443 or 22 respectively, but may well be different for Enmuster). A SSH tunnel provides the means to access that nominated end point via an intermediate computer, when the end point isn't accessible from the outside world (it's behind a firewall for example). To do this you must be able to log in to the intermediate computer using SSH. (Typically, you'd use PuTTY to do this on Windows, or the ssh command on Linux).
Authentication for this login uses a username and either a key-pair or a password. The private key stays on the client and the public key on the server. (These are not the same keys that Enmuster uses to authenticate itself to the Enmuster Server!). PuTTY and its companion programs PuTTYGen and Pageant can manage keys for you - see above
A tunnel needs three things to work, in addition to the URL (which includes both domain and port) which will eventually be accessed from the far end of the tunnel (this URL is unchanged, but may be a URL that is otherwise inaccessible).
) if you need to; it will use local port 8002
unless you say otherwise.So, to add a tunnel to a URL, click 
next to the URL. Enter the login username, the login
password or private key, as above, and the hostname or
hostname:port in the three boxes. To remove a
tunnel, click next to it.
If you export a project, tunnel credentials (from the first two boxes) are removed!
Each time you deploy changes for a folder, you can arrange to automatically increment a revision number stored in one of your files. That file can then be read or executed by other components of your site, to display it on an "about" page, for example. Another helpful use for this number is to override the browser cache when updating Javascript or CSS files etc. For example, let's say you have the following in your HTML, and this is generated using PHP:
<link rel="stylesheet" type="text/css" src="/style.css">
style.css may get stuck in the browser cache when you deploy new HTML which depends on it. To avoid this you can put a version query string on the end, like this:
<link rel="stylesheet" type="text/css" src="/style.css?v=121">
Let's say your revision number is in a file called revision.php as follows:
<?php /* ~revision~ */ function revision() { return 121; } ?>
Notice the text ~revision~ in the comment. Then, having included that file somewhere in your PHP, use something like this for the stylesheet link:
<link rel="stylesheet" type="text/css" src="/style.css?v=<?php echo revision(); ?>">
The idea is then to ensure this number gets updated with each code change (which makes the browser think, correctly, that this style.css is a different file).
To do this, add the file to the automatically update revision number... section for your folder by dragging the file (revision.php in our example) from your computer's file browser to the space provided.
When this is set, before uploading to any URLs, Enmuster locates the file and looks for the first line containing ~revision~. It then looks for the first decimal number following, and replaces it with the next number in sequence. There can be anything non-numeric on the same line between ~revision~ and the number.
To get the ball rolling, you'd want to include a file containing
... ~revision~ ... 0 ...
in your local folder. That way, it will be incremented to 1 on the first deployment. You can also reset the number just by editing the file, but bear in mind this may affect colleagues working on the same project.
Upgrade files are a means of applying updates which require more than just a file to be replaced, for example, reorganising a database in some way to match changes in the code that runs a web app.
An upgrade file should only be run once, but there will be several of them as time goes on. Therefore, the files are identified by a pattern rather than individually, but are only considered eligible to be run as an upgrade if they are new - they don't already exist on the server.
Choose a distinctive pattern, such as *.upgrade or *.upgrade.php so you don't accidentally run an old file as if it were an upgrade.
If a deployment finds more than one such file, the order in which they are run is not specified.
An upgrade file can be anything that can be run on the server which can validly start #! or <?php. Files that start #! are simply executed: what processes them depends on what follows the #! in the usual Linux shell way. For example #!/bin/sh or #!/usr/bin/perl. Files starting <?php are run with the php command line interpreter: not the web server. In both cases the working directory is the directory where the maintenance file is located.
A particularly common case is to execute a set of SQL commands (say for MySQL), but you can't just run these because you need a username and password to access the database. While you could put these in the file, it would avoid duplication to use the same configuration file as the main web app to obtain these. So you could, for example, have a an upgrade file containing SQL commands which is run using a little PHP file (using the #! in the SQL file to invoke it) which looks up the credentials and passes them and the SQL code on to mysql.
Do not put upgrade files in the html directory hierarchy where visitors can execute it! That would cause havoc by re-running an upgrade twice - or worse.
To add, remove or replace an upgrade pattern, click on the existing one in the upgrade sction for the folder (or [none] if there isn't one yet) and type the pattern. The patterns are the same simple patterns as for exclusions, just using * as a wildcard, but there is only one, not a list of patterns.
It is sometimes necessary to indicate to or prevent users from making changes while you are in the middle of an update. You can manage this automatically. How you indicate this depends on your own site, of course. Typically it might involve creating a file or setting a field in a database, which, if it exists, causes your website to put up a holding page.
This is managed by identifying a file to Enmuster which will be
executed on the server. Add such a file by
dragging it from the computer's file browser (Windows Explorer,
Finder etc.) to the box indicated in the turn maintenance mode
on and off... section for a folder. To
remove it, press alongside. To
replace it, drag the new file onto the name of
the old one.
The maintenance file can be anything that can be run on the server which can validly start #! or <?php, just like an upgrade file - see above.
The file is run twice, once at the start and once at the end of each deployment. It is passed a parameter on or off respectively. So for example, you can determine this in PHP using $argv[1] (and the syntax is actually the same in a Linux shell).
Do not put this file in the html directory hierarchy where visitors can execute it! They would then be able to turn your lock on.
Change settings by clicking in the top right of Enmuster's home page.
If change your client name, you will need to rename your public key in the Enmuster Data Directory on each server you deploy to.
If your key pair is compromised, you can generate a new one here. You can also copy the public key for pasting to the servers, or save it to a file.
If you use tunnels, you can change the local port of the tunnel here, should you need the default, 8002, for something else.
Finally, you can obtain the code for the server side of Enmuster here. The file contains instructions for installation, and you need to edit just one line, right at the top of the file, to identify your Enmuster Data Directory.
Enmuster is Copyright © 2015 David Earl and licensed under the MIT License. Find it on Github.
Enmuster is built using nw.js, licensed under the MIT License, which in turn deploys node.js and Chromium. It also makes use of the following third-party components under the MIT License unless stated: