Static website hosting with rsync-based upload: docroot
docroot is a simple but quite useful web App for static file hosting.
It is useful if:
You manually edit all HTML files of your website, and your Site does not need to run any kind of server-side scripts.
You can run PHP scripts simply by uploading them, but there is no server-side infrastructure (like a database) for them. However, they can access whatever local files have been uploaded.
For example, the UBOS website at
docroot at the root of the Site,
as all of its content is statically generated.
Here is how to use
On your computer (not the UBOS Device), pick, or create an SSH key pair that will be used to securely upload your content to your to-be-created Site. This can be the same key pair that you use with your UBOS Staff, or a different key pair. For more info about SSH and how to create an SSH key pair, see How to use SSH.
You create a Site at which to run
ubos-admin createsiteon your UBOS Device. Specify
docrootfor the App, and any Context Path you wish.
ubos-admin createsitewill then ask you for the filename of a public key. Enter the path to that file (usually called
ubos-admin createsiteis complete, you can now securely upload data to your new static Site, using
ssh, which is the most efficient and secure method we could think of.
You need only one more piece of information, which is the AppConfigId of the deployment of
docrootthat you just created. (This is necessary so UBOS knows which one you are talking about, in case you have more than one installation of
docrooton the same Device.) You determine it by executing on your UBOS Device:
% ubos-admin listsites --detail
To upload a file, or an entire directory hierarchy of files with your default SSH keypair, use this command:
% rsync -rtlvH --delete-after --delay-updates --safe-links -e ssh <FROM> docroot@<HOST>:<APPCONFIGID>/
<FROM>> is the local file or directory to upload,
<HOST> is the name of the
UBOS device to upload to, and
<APPCONFIGID> the AppConfigId you just determined.
Note that the destination path in this command is not the usual path to the file on the remote
Device, but the AppConfigId (plus potentially a local path from there):
docroot will figure out the absolute path.
If you want to use a non-default SSH keypair, you need to add which to the command, so the command becomes:
% rsync -rtlvH --delete-after --delay-updates --safe-links -e 'ssh -i <PRIVKEY>' <FROM> docroot@<HOST>:<APPCONFIGID>/
<PRIVKEY> is the name of the file that contains the private key.
Admittedly, this command is a handful, so let’s unpack this:
rsync: we use the
rsynccommand for uploading, as it is smart and can intelligently skip everything you uploaded before, by just transferring data that is new or has changed since the last upload. This is particularly useful for the many static websites where only little content changes from upload to upload.
rsyncto recursively upload an entire directory hierarchy, and things like that.
rsyncto delete files that were previously uploaded but don’t exist locally on your computer any more.
--delay-updates: useful for long uploads; tell
rsyncto do the actual update of the website in one swoop at the end of the upload, instead of incrementally as files arrive one by one.
--safe-links: in case you are using symlinks, keep those links intact during the upload as long as they are safe.
-e ssh: tell rsync to transfer data over
ssh. This encrypts all uploaded data, and uses SSH access control so only you can upload to your Site, because only you have access to your SSH private key. This uses your default SSH private key.
-e 'ssh -i <PRIVKEY>: instead of using the default SSH private key, use the private key contained in file
If you execute this command regularly, you may want to create an alias or script for it on your local computer.
As soon as the
rsync command is complete, when you visit the URL at which you installed
docroot, your content should be displayed in your web browser.