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
To keep a paper or PDF copy: use your browser’s Print command, select Save as PDF or your printer, choose A4 and turn off browser headers and footers.
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. |
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.
- A Windows computer or Mac with an internet connection and permission to install software.
- The Coverstead Community ZIP. Download it from the supplied release link. Extract the ZIP rather than opening files inside it.
- 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.
- 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 version03 / 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 buildThe first build downloads the software it needs. It may take several minutes. You do not need to understand every progress line.
2. Create your installation settings.
docker compose run --rm coverstead npm run setupWhen 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.
3. Start Coverstead.
docker compose up -dOpen your web browser and type http://localhost:3100/onboarding.
To check that the container is running:
docker compose psTo stop it when you have finished practising:
docker compose stopTo start it again later:
docker compose startYour 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.
- Paste the installation token into the first box.
- Enter your name and email address.
- Choose a unique password with at least 16 characters. A long, memorable passphrase works well. Save it in a password manager.
- Select Create account.
If you lost the installation token before creating your account, display it again:
docker compose run --rm coverstead npm run tokenIf 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 step | What to enter |
|---|---|
| 1. Your venue | Name, telephone, email, address, website, time zone, public opening hours and accessibility notes. |
| 2. Tables & spaces | Every table’s number, seats and area. Add only the table combinations you really permit. Set the maximum number of seated guests. |
| 3. Service times | Lunch and dinner for each weekday. Set opening, last booking and walk-in service closing. Untick both for a closed day. |
| 4. Kitchen & bookings | Arrivals per rolling time window, booking duration, reset buffer, online party maximum, booking notice and booking horizon. |
| 5. Brand & menus | Your 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 & policies | Group threshold, deposit, pre-order notice, optional seasonal event, cancellation policy and privacy-notice link. |
| 7. Review & open | Check every setting, confirm the review box and save. |
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.
- Open
http://localhost:3100/bookin another browser tab. - Choose a date when your venue serves food, a party size and an available time.
- 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.
- Finish the booking. Keep the reference shown on screen.
- Return to
/admin, sign in and select the same date. Check that the booking, table and guest count appear. - Use Manage to change the time or add a private staff comment. Check the printable service sheet.
- Cancel the test booking. Check that it leaves the active diary and that its capacity is available again.
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.
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.
- 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.
- 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.
- 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.
- Build the public version:
docker compose -f compose.public.yaml buildCreate fresh production settings. Type your real HTTPS booking address when prompted:
docker compose -f compose.public.yaml run --rm coverstead npm run setupFor 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 -dCaddy 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.
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.
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 coversteadThe 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/bookYou 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 coversteadInside 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.
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.
- Read the release notes and make a protected backup.
- Stop Coverstead outside service.
- Replace application files with the new release, keeping the same project folder name, data volume, private configuration and your real Caddyfile.
- Rebuild and restart:
docker compose build
docker compose up -dCheck 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 coversteadA 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.
| Problem | Try 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 coversteadWhen 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 startFor 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_PORTDo 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.
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:
- Docker Desktop installation and operating-system requirements
- Docker Compose guide
- Caddy automatic HTTPS and DNS requirements
- Opalstack Node.js deployment guide
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.