Who this is for
This guide is for teams that want HandHoldly running on a server they control, rather than using it only through the hosted version. That might be a software company with a platform team, a small support or documentation group with its own infrastructure, or a registered charity running a web service that needs its help content kept on its own systems.
In plain English, self-hosting means you run the application on a machine you manage, and you decide where its files live. HandHoldly can be hosted with Docker or Coolify, and its recordings can be stored in any S3-compatible storage service. If you are not sure whether that is the right route for you, that decision is covered in our general self-hosting post. This article assumes you have already decided and want to get on with it.
What you need before you start
You need two things in place before you touch any settings.
The first is a server that runs either Docker or Coolify. If your team already uses Coolify to deploy other apps, adding HandHoldly is usually a matter of creating a new application in the same place. If you use plain Docker, you will need a machine where you can run containers and manage them with the usual tools your team already knows.
The second is a place to keep recordings. HandHoldly stores the narrated videos it produces in S3-compatible storage. That could be a storage service from a cloud provider, or a storage server you run yourself, as long as it speaks the same protocol. Before you start, gather the details your storage provider gives you:
- the endpoint address
- the bucket name, which is the container for your files
- an access key and its matching secret
- the region, if your provider asks for one
Keep these somewhere safe and only share them with the people who need them. Do not paste them into a shared document or a chat thread.
It also helps to have a domain name ready for the app, and a second person on hand who can check the result with you. Walkthroughs are easier to confirm when two people look at the same output.
Choosing S3-compatible storage for recordings
It helps to be clear about what goes where. The application itself runs on your server. The recordings, which are the video files produced from your scripts, go to your S3-compatible bucket. Keeping them separate has practical benefits.
First, the server can be replaced or rebuilt without losing your recordings, because they sit in storage that is independent of the machine running the app. Second, storage can grow on its own terms, so a long run of videos does not fill the disk of the server doing the work. Third, your backup routine for recordings can be handled at the storage level, which is often simpler than backing up a whole server.
When you choose a storage service, look for three things: that it supports the S3 protocol, that you can create a bucket and a set of access credentials for it, and that you can see where your files are stored. Do not assume that every service behaves identically. Test the connection before you rely on it, which is what the setup steps below are for.
A step-by-step outline of the setup
The setup has three stages: get the app running, connect the storage, and run a first test walkthrough. Work through them in order.
Stage one: get the app running.
- If you are using Coolify, create a new application and point it at the HandHoldly deployment source you have been given. If you are using Docker, pull the image and prepare a container with the environment values the app needs.
- Set the public address for the app to the domain you have chosen. Check that the domain resolves to your server before you go further.
- Start the application and wait for it to report that it is running. Open the address in a browser and confirm the login page loads.
If the page does not load, check the logs for the container or application first. Most early problems are a wrong address, a port that is not open, or a missing value in the environment settings.
Stage two: connect the storage.
- Enter the endpoint, bucket name, access key, secret and region from your storage provider into the storage settings.
- Save the settings and use the connection test if the app offers one.
- Check the bucket directly, using the tools your storage provider gives you, to confirm that the bucket exists and that the access key has permission to write to it.
Do not move on until the connection test passes and you can see a file appear in the bucket. A storage connection that looks correct but fails on the first upload is much harder to debug later, when you have a real script waiting.
Stage three: run a first test walkthrough.
- Create a short script with two or three steps. Keep it simple: open a page, click one button, and confirm the result.
- Run it against a test environment rather than your live product.
- Wait for the run to finish, then open the output and check each part.
The test walkthrough is the moment the whole chain is tested for the first time. It shows whether the app can reach the product, whether the recording can be written to storage, and whether the output can be read back.
Checking it works
A single short walkthrough is enough to confirm the setup. You are looking for three outputs from one script: the narrated video, the live guide and the step-by-step help article.
For the video, open the file from your storage bucket, not just from the app. Play it through and check that the narration matches the steps and that the recording shows the right screens. For the live guide, load a page that uses the guide and step through the same script to confirm each step appears in the right place. For the help article, open it and check that the screenshots and step text line up with what you just ran.
If one of the three is missing, the problem is usually narrow. A missing video often points to the storage connection. A missing guide often points to the script tag or the browser extension not being set up on the page. A missing article often points to a step that did not finish. Fix the one that failed, then run the test again from the start, so you know the whole chain works together.
Once all three appear, you have a working base to build on. It is worth saving a copy of that test script, because you will use it again when you check future changes.
Looking after it afterwards
Setting up is the easy part. Keeping the system healthy is the ongoing work, and it is worth deciding who owns each job before you need it.
Backups. Your recordings sit in your storage bucket, so back them up according to your storage provider's options or your own routine. Your app configuration and any database files belong on the server side, so include them in your normal server backups. Write down where each lives and who can restore it.
Updates. Decide who applies updates to the application, and how often. Test an update on a copy or in a test environment before you apply it to the live instance. After every update, run your test walkthrough again.
Nightly re-checks. HandHoldly re-checks scripts every night. When a step no longer works, it flags that step, fires your webhooks and emails the owners named against the script, naming the step that has broken. For that to help, the owners need to be real people who will read the email, and the webhooks need to point somewhere someone watches. Check, once a month, that the re-check still runs and that the email reaches the right inbox. A re-check flags a broken step, but someone still has to fix it.
A short checklist to share with your team
- Server ready with Docker or Coolify, and a domain pointed at it
- Storage bucket created, with an access key that can write to it
- Storage details kept somewhere safe and shared only with the people who need them
- App running and the login page loading
- Storage connection test passing, and a test file visible in the bucket
- Test walkthrough produced, with the video, live guide and article all checked
- Backups defined for recordings and for server configuration, with an owner for each
- Updates tested on a copy before they reach the live instance
- Nightly re-check emails reaching the named owners, checked monthly
- Webhook destinations confirmed and watched by someone
If you want to see what the output looks like before you set anything up, See how it works shows how one script becomes a narrated video, a live guide and a step-by-step help article.