Free software. A practical helping hand.

The friendly
self hosting
installation manual.

This is the first pilot release. Practise with test bookings before relying on it for a service. Live hosting, email and backup recovery need checking on your own installation.

From one hospitality business to another.

I’m Alistair, landlord of The Red Lion in Kilsby. I had a reservation app built for my pub, and it made a real difference to my team, our bookings and the service we could offer.

I know how difficult it can be to run an independent hospitality business, especially when every cost seems to be heading in the wrong direction. I wanted to give something useful back. That’s why the self hosted version of Coverstead is free and open source.

You do not need to be a programmer to follow the practice installation in this guide. Work through one step at a time. When you see a dark command box, copy that command into your terminal and press Enter. The “You should see” boxes tell you what success looks like.

Taking bookings from the public adds responsibility for a server, email and backups. The online route explains those extra steps separately. If you would rather have that looked after, the planned managed service includes your first month free, then £10 per venue per month or £100 per year paid upfront.

Alistair
The Red Lion, Kilsby

01 / START HERE

Choose the right route.

I want to…Use this route
Try it on my own Windows PC or Mac.Chapters 2–6. Docker Desktop runs everything locally. No domain or public server needed.
Accept real bookings on the internet.Practise first, then chapter 7. Use an always-on server, a domain and HTTPS.
Use existing Node.js hosting such as Opalstack.Chapter 13. Use your hosting provider’s assigned application port and start/stop tools.
A laptop practice installation is not a public booking website. Guests cannot book if the computer is off, asleep or unavailable. Do not publish a localhost address.

Free means the software is free. Self hosting may still involve a server, domain and email-provider bill. Coverstead does not charge a software licence fee or commission on bookings.

The Community package includes the reservation diary, guest booking page, kitchen and table rules, customer history, consent records, loyalty tools and printable service sheets. The Enterprise service adds convenience and team administration. Paid enrolment is not yet open in this preview release.

02 / GET READY

Gather a few things.

  1. A Windows computer or Mac with an internet connection and permission to install software.
  2. The Coverstead Community ZIP. Download it from the supplied release link. Extract the ZIP rather than opening files inside it.
  3. Docker Desktop, downloaded from Docker’s official website. Pick Windows or Mac, follow its installer and restart if requested. On Windows, follow Docker’s instructions if it asks to enable WSL 2. Review Docker’s current licence terms for your organisation.
  4. Your table list, service times, kitchen arrival limit, venue contact details, logo and menu PDFs.

Put the extracted folder somewhere easy to find, such as Documents/coverstead. When you open it, you should see compose.yaml, Dockerfile and package.json.

Open a terminal in that folder.

Windows: open the folder in File Explorer, right-click an empty area and choose Open in Terminal. PowerShell is fine.

Mac: open Terminal from Applications → Utilities. Type cd with a space, drag the extracted Coverstead folder into the Terminal window, then press Enter. Dragging the folder inserts its location for you.

Check Docker is ready:

docker compose version
You should see: a Docker Compose version number. If the command is not found, open Docker Desktop and complete its setup before continuing.

03 / YOUR FIRST INSTALLATION

Three commands to get it running.

Keep Docker Desktop open. Run these commands from the Coverstead folder, one at a time.

1. Build the app.

docker compose build

The first build downloads the software it needs. It may take several minutes. You do not need to understand every progress line.

You should see: a successful build and a normal terminal prompt, without a red error at the end.

2. Create your installation settings.

docker compose run --rm coverstead npm run setup

When asked for a website address, press Enter to accept http://localhost:3100. The installer creates a private installation token. Copy that long code somewhere private for the next chapter. It is used once to claim your own installation.

The token is not your future login password. Do not post it in a public forum. Re-running setup keeps your existing configuration instead of overwriting it.

3. Start Coverstead.

docker compose up -d

Open your web browser and type http://localhost:3100/onboarding.

You should see: “Create your owner account”. Use localhost exactly for this practice setup; changing it to an IP address can cause a security check to reject form submissions.

To check that the container is running:

docker compose ps

To stop it when you have finished practising:

docker compose stop

To start it again later:

docker compose start

Your data survives stopping and starting. It is stored in a Docker data volume, separate from the app software.

04 / CLAIM YOUR INSTALLATION

Create your owner account.

  1. Paste the installation token into the first box.
  2. Enter your name and email address.
  3. Choose a unique password with at least 16 characters. A long, memorable passphrase works well. Save it in a password manager.
  4. Select Create account.
You should see: the seven-step venue setup screen. Your installation cannot be claimed again by someone else.

If you lost the installation token before creating your account, display it again:

docker compose run --rm coverstead npm run token

If an owner already exists, use Staff sign in or /admin. The installation token no longer grants access after that first owner has been created.

05 / MAKE IT YOURS

Tell Coverstead how your venue works.

Use Save progress whenever you need a break. The starting seating layout is a sample pub template, not a survey of your venue.

Setup stepWhat to enter
1. Your venueName, telephone, email, address, website, time zone, public opening hours and accessibility notes.
2. Tables & spacesEvery table’s number, seats and area. Add only the table combinations you really permit. Set the maximum number of seated guests.
3. Service timesLunch and dinner for each weekday. Set opening, last booking and walk-in service closing. Untick both for a closed day.
4. Kitchen & bookingsArrivals per rolling time window, booking duration, reset buffer, online party maximum, booking notice and booking horizon.
5. Brand & menusYour welcome line, colour, logo and menus. Upload PNG/JPEG/WebP logos and PDF menus, up to 5 MB each, or link existing public files.
6. Groups & policiesGroup threshold, deposit, pre-order notice, optional seasonal event, cancellation policy and privacy-notice link.
7. Review & openCheck every setting, confirm the review box and save.
Money fields use pence. Enter 2500 for a £25 regular group deposit, or 500 for a £5 seasonal deposit per guest. A regular group deposit is per booking; a seasonal deposit is per person.

Kitchen example: “16 arrivals in 30 minutes” means any rolling half-hour, not just 12:00–12:30 and 12:30–13:00. A booking at 12:20 can affect one at 12:40.

Table duration example: a 90-minute booking starting at 12:00 holds the table until 13:30. A 15-minute reset buffer makes it unavailable until 13:45, unless staff mark the party completed and release the table.

Existing bookings keep their stored duration and deposit. Changing opening hours does not cancel existing reservations. The app will stop you removing or shrinking a table that an active future booking uses.

The recorded retention period is a planning preference only: this release does not automatically delete guest data. Accessibility notes are requests for your team to confirm, not guaranteed automatic table allocation.

06 / A REHEARSAL BEFORE SERVICE

Try a booking before you share the link.

  1. Open http://localhost:3100/book in another browser tab.
  2. Choose a date when your venue serves food, a party size and an available time.
  3. Use your own contact details and the name Test Booking. Add a harmless request such as “Test only”. Do not use a real customer’s details.
  4. Finish the booking. Keep the reference shown on screen.
  5. Return to /admin, sign in and select the same date. Check that the booking, table and guest count appear.
  6. Use Manage to change the time or add a private staff comment. Check the printable service sheet.
  7. Cancel the test booking. Check that it leaves the active diary and that its capacity is available again.
You should see: one saved booking, visible only to signed-in staff, with the expected table allocation. Repeated submission of the same guest request should not create a duplicate.

Also practise a closed day, a party larger than the online limit, a full kitchen window, a blocked session and a walk-in during an open service. Walk-ins are only available during the configured service, so it is normal to see “no open dining service” outside those hours.

Email is deliberately paused until it is configured. A booking can be saved without an email being sent. Clear or cancel practice records before enabling a live sender; queued notices may otherwise be delivered later.

07 / ACCEPT REAL ONLINE BOOKINGS

Use an always-on server and a domain.

This route is for a dedicated Linux server where Docker Compose is installed and ports 80 and 443 are available. If your hosting provider already runs other websites or controls the web server, use chapter 13 or ask them to connect the app to their existing HTTPS proxy. Do not replace a shared server’s web configuration.

  1. Arrange a server with Docker and Compose installed. Keep its SSH login private. Ask the host to help if you are unfamiliar with server administration.
  2. Choose a booking address, such as bookings.yourpub.co.uk. In your domain’s DNS settings, create an A record for bookings pointing to the server’s public IPv4 address. Only add an AAAA record if the host supplies working IPv6.
  3. Upload and extract the Coverstead package into a new folder on the server. Keep it separate from any existing live app. Open a terminal in that folder.
  4. Build the public version:
docker compose -f compose.public.yaml build

Create fresh production settings. Type your real HTTPS booking address when prompted:

docker compose -f compose.public.yaml run --rm coverstead npm run setup

For example, enter https://bookings.yourpub.co.uk. This enables secure cookies. The installer does not overwrite an existing configuration; start in a fresh production project if you used another address during practice.

Copy Caddyfile.example to a new file named Caddyfile. Replace the example domain with your real booking domain, leaving the other lines intact:

bookings.yourpub.co.uk {
    reverse_proxy coverstead:3100
}

Make sure the server firewall allows incoming TCP ports 80 and 443. Keep the internal app port off the public internet. Then start:

docker compose -f compose.public.yaml up -d

Caddy obtains and renews the HTTPS certificate when the domain and network are configured correctly. Open your real https://…/onboarding address and repeat owner setup, venue setup and your test booking.

You should see: your website loading over HTTPS without a certificate warning. Check it from a phone using mobile data as well as from your own Wi-Fi.

For this route, add -f compose.public.yaml after docker compose in all the later management commands. For example, docker compose -f compose.public.yaml logs --tail=80.

One venue, one installation. Each venue needs a separate database, uploads and hostname. Never point several independent venues at one owner setup or run several workers against the same SQLite file.

08 / CONFIRMATIONS AND UPDATES

Connect your email sender.

Ask your email provider for its SMTP host, port, username, password and verified sender address. Follow that provider’s instructions for sender verification and any SPF, DKIM or DMARC records. Your venue contact email and SMTP account can be different.

First review and cancel any practice bookings. Then stop the app and run the guided email setup:

docker compose stop coverstead
docker compose run --rm coverstead node scripts/email-setup.js
docker compose start coverstead

The password is hidden while you type. Choose port 587 or 465 as your provider specifies. Only type yes at the verification question once the sender and required DNS are confirmed. Otherwise the settings are saved with delivery paused.

Make a new booking using your own email address. Check:

  • The confirmation arrives, including the junk folder.
  • It uses the correct venue name and reply address.
  • Menus or forms are current. Uploaded files are attached; external menu URLs are linked.
  • Updates and cancellations arrive too.
  • Private staff comments do not appear in guest emails.

Messages are queued and retried. An email being queued is not proof it was delivered. Check the staff notice and server logs if messages do not arrive. Never paste SMTP passwords into a public support request.

Deposits in this release are recorded after a payment taken by phone or in person. There is no general online card checkout, SMS delivery or automatic refund flow enabled.

09 / OPEN THE DOOR

Add a booking button to your website.

Once your online checks pass, add a button labelled Book a table to your existing website. Its link is your public address with /book at the end:

https://bookings.yourpub.co.uk/book

You can use the same link on social profiles or a QR code. A website developer can add it without rebuilding your site. This release uses a link to a booking page, not an embedded iframe.

Before your first real service

  • Check the table map, largest party, service cutoffs and kitchen capacity with the team.
  • Check normal bookings, pre-orders and any seasonal event.
  • Check real email delivery, including a cancellation.
  • Check the logo, current menus, telephone, policies and privacy notice.
  • Make and restore a backup using a practice environment.
  • Show staff how to manage arrivals, completed visits, no-shows, walk-ins and cancellations.
  • Print a service sheet as a fallback if the internet is unavailable.

The app records dietary and accessibility requests, but the team must still confirm what the venue can provide. A booking note is not a substitute for your normal allergy conversation.

10 / LOOK AFTER YOUR DIARY

Backups are part of running your own copy.

Choose someone to be responsible for backups. Make one regularly and before an update. A backup on the same server is not enough: copy it to another protected location.

Make a consistent backup.

Do this outside service because the app is briefly stopped:

docker compose stop coverstead
docker compose run --rm coverstead npm run backup
docker compose cp coverstead:/app/data/backups ./coverstead-backups
docker compose start coverstead

Inside coverstead-backups is a timestamped folder containing the database, uploaded assets and private configuration. Copy that folder to an encrypted drive or a protected backup service.

Backups contain guest details and credentials. Treat them like confidential business records. Do not put them in your public website, an open sharing link or an unprotected email attachment.

Practise recovery on a spare installation.

Restore into a separate, stopped test installation first. Do not overwrite your only live copy to see whether recovery works. The detailed restore procedure is in docs/OPERATIONS.md in the package. It includes pausing outgoing email so restoring an old queue cannot silently resend messages.

For a live failure, preserve the current data before replacing it, choose the intended backup, restore the database, assets and configuration together, then restart and check your owner login and recent reservations. Keep email paused until the restored queue has been reviewed.

Never run docker compose down -v as routine maintenance. The -v option removes the data volume and can delete your bookings. Stopping or restarting the app does not require deleting its data.

11 / KEEP IT IN GOOD SHAPE

Updates and forgotten passwords.

Install an update.

  1. Read the release notes and make a protected backup.
  2. Stop Coverstead outside service.
  3. Replace application files with the new release, keeping the same project folder name, data volume, private configuration and your real Caddyfile.
  4. Rebuild and restart:
docker compose build
docker compose up -d

Check owner login, the diary, a test booking, menus and email. Do not run multiple copies against the same database. Changing the project folder name can make Docker select a different data volume, making the app appear empty.

Reset a forgotten password.

You need access to the host computer or server. Stop the app, run the reset helper, enter the staff email and a new passphrase, then restart:

docker compose stop coverstead
docker compose run --rm coverstead node scripts/reset-password.js
docker compose start coverstead
You should see: “Password changed.” Existing browser sessions end when the app restarts. Sign in with the new password.

A person with server access can access the database and reset accounts. Protect the hosting account as carefully as the app login.

12 / TROUBLESHOOTING

Start with what you can see.

ProblemTry this
“docker” or “compose” is not found.Install and open Docker Desktop. Reopen your terminal. Check docker compose version.
The build cannot download files.Check your internet connection and whether a workplace firewall blocks Docker Hub or the npm registry. Ask the network administrator rather than disabling security tools.
“Configuration already exists.”This is protective. Setup has preserved your existing settings. Continue with the current installation; use the saved address.
The page will not open.Check docker compose ps. Confirm Docker is running and use the exact configured address. Read the logs below.
“Please submit from this website.”The address used in the browser differs from PUBLIC_URL. For the practice guide, use http://localhost:3100, not 127.0.0.1.
Login seems to work but immediately signs out.Secure cookies require HTTPS. Local practice uses HTTP with COOKIE_SECURE=false; a real public site should use HTTPS with COOKIE_SECURE=true.
“Database is already in use.”Stop the other Coverstead process. Each database allows one worker. Do not delete a lock while an app is running.
No booking times appear.Check the date, service times, closed sessions, notice period, party size, seasonal date rules and how far ahead bookings are allowed.
A table looks free but booking is refused.Check kitchen arrivals, total seating capacity, table combinations, reset buffer and nearby future reservations.
A walk-in is unavailable.It must be during an open dining service, with sufficient seats and no table overlap. A strict kitchen policy may also block it.
Emails are waiting.Check the SMTP setup and verified sender. Queued is not delivered. After repeated failures, ask the installer to review delivery logs and retry only after fixing the cause.
There is an HTTPS warning.Check DNS and the hosting certificate. For the Caddy route, check ports 80/443. Do not publish the link until the warning is resolved.
Bookings appear to have disappeared.Check diary date/filter and Docker project/volume names. Stop and inspect before creating a new empty database or restoring over an existing one.

View the recent app messages.

docker compose logs --tail=80 coverstead

When asking for help, provide the version, route used, exact error and the step where it happened. Remove passwords, tokens, guest details and payment information from any logs or screenshots.

13 / EXISTING NODE.JS HOSTING

The Node.js and Opalstack route.

If you already have a Node.js host, Docker is not required. Ask the provider for a supported Node runtime, the application folder, the assigned internal port and its start/stop method. This package supports Node 20 or later; use a maintained runtime supplied by the host.

In the extracted app folder:

npm ci --omit=dev
npm run setup
npm start

For an Opalstack application, activate its Node environment as documented by Opalstack, then use the assigned port. This is an example command with placeholders you must replace:

node scripts/setup.js --url=https://bookings.yourpub.co.uk --port=YOUR_ASSIGNED_PORT

Do not literally enter YOUR_ASSIGNED_PORT. Find the number in your app’s Opalstack information, README or start script. The app must listen on that port; creating a domain record alone does not change it.

Point the Opalstack site route at the Node app, attach the domain and enable HTTPS. Update the app’s start script to run node server.js from the Coverstead project folder. Preserve the original blank project and start/stop scripts before changing them.

On shared hosting, keep the app, database, uploads and process separate from every other venue. Do not replace another app’s start script, reuse its port or copy its database. The detailed owner-specific deployment notes in docs/OPALSTACK.md target the new coverstead stack only.

The email and password helpers work with Node too. Stop the service using the host’s controls first, then run node scripts/email-setup.js, npm run backup or node scripts/reset-password.js from the app folder. Restart with the host’s normal start command.

A FEW USEFUL WORDS

Plain-English reference.

Self hosted
You run a copy on a computer or server you control. You look after its availability, updates and backups.
Docker
A way to package the app and its software requirements together, so you do not have to install each one separately.
Container
The running copy of that package. Stopping the container does not need to delete your data.
Volume
The separate storage where your bookings, settings and uploaded files live.
Terminal
A window for entering commands. Copy the commands exactly, one at a time.
Domain and DNS
Your web address and the settings that point it to the right server.
HTTPS
An encrypted connection between a visitor’s browser and your website.
SMTP
The email provider connection the app uses to send confirmations and updates.
PUBLIC_URL
The exact address people use in their browsers. It must match the installation’s configuration.
Open source
The code is available under the included MIT licence. You can use and adapt it subject to that licence. It is not a promise of unlimited free hosting or support.

Official help and references

Checked for this guide on 16 November 2026:

The application tests and a local browser rehearsal cover owner sign-in, venue setup and a guest booking. Docker image startup, SMTP delivery and your own backup recovery still need checking. Treat the first server installation as a pilot and complete the rehearsal before accepting live bookings.

Full tables. Calmer service.
From one independent to another.