BookCars on Ubuntu 24.04 on Azure User Guide

Overview

BookCars is a popular open source, self hosted car rental and booking platform built on the MERN stack. It gives you a complete rental business in one application: a customer storefront where visitors search and filter available cars, choose pick up and drop off locations and dates, and book and pay online, and an administrator panel where you manage suppliers, vehicles, locations, bookings and customers. A Node and Express REST API backed by MongoDB drives both, with multi currency and multi language support and online payment through Stripe or PayPal.

The cloudimg image installs BookCars natively (no Docker), pinned to release v8.7:

• MongoDB 8.0 runs as a single node replica set (rs0) bound to 127.0.0.1, with key file internal authentication and authorization enabled.
• The BookCars API is pre built and managed by bookcars-api.service on 127.0.0.1:4002.
• The customer storefront and admin panel are compiled to static bundles and served by nginx: the storefront on port 80 and the admin panel on port 8080. nginx reverse proxies /api and /cdn on both to the API, so the compiled front ends call the API same origin and the appliance works by IP address or by your own domain with no rebuild.

Secure by default, no default login: the upstream project seeds a fixed default administrator; this image never does. On first boot a bookcars-firstboot.service oneshot generates a unique administrator, unique application secrets (BC_JWT_SECRET, BC_COOKIE_SECRET), and a unique MongoDB credential and key file, initialises the database, creates exactly one administrator, and writes the login to /root/bookcars-credentials.txt (readable only by root), then disables itself. No shared password, database user or pre seeded record exists in the image.

Bring your own payments and email: the appliance ships safe placeholder values for Stripe, PayPal and SMTP so the platform boots and serves fully without them. You add your own keys to enable live checkout and transactional email (covered below).

What is included:

• BookCars v8.7 installed natively on Ubuntu 24.04 LTS
• MongoDB 8.0 single node replica set, loopback only, key file + auth
• The Node API under systemd and the storefront + admin panel served by nginx
• A fully patched OS with unattended security upgrades enabled
• 24/7 cloudimg support

Prerequisites

• An Azure subscription and the BookCars on Ubuntu 24.04 LTS image from the Azure Marketplace.
• A VM size with at least 2 vCPUs and 4 GB RAM (for example Standard_B2s).
• Inbound access to port 80 (storefront) and port 8080 (admin panel), plus port 22 for SSH, in the VM's network security group. Add 443 if you enable HTTPS.

Step 1: Deploy from the Azure Portal

1. In the Azure Portal, choose Create a resource and select the BookCars image.
2. Pick your resource group, region and a size such as Standard_B2s.
3. Under Networking, allow inbound 80, 8080 and 22.
4. Create the VM and wait for it to boot. First boot provisions the database, generates the per instance secrets and creates your administrator.

Step 2: Deploy from the Azure CLI

az vm create \
  --resource-group my-bookcars-rg \
  --name bookcars \
  --image <bookcars-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

az vm open-port --resource-group my-bookcars-rg --name bookcars --port 80 --priority 900
az vm open-port --resource-group my-bookcars-rg --name bookcars --port 8080 --priority 910

Step 3: Connect via SSH

ssh azureuser@<vm-ip>

Step 4: Verify the services are running

MongoDB, the BookCars API and nginx come up automatically after first boot. Confirm they are active and listening:

sudo systemctl is-active mongod bookcars-api nginx
ss -tln | grep -E ':27017 |:4002 |:80 |:8080 '

You should see all three services active, MongoDB on 127.0.0.1:27017, the API on 127.0.0.1:4002, and nginx serving the storefront on :80 and the admin panel on :8080.

Step 5: Secure by default, no admin ships

The image ships no known credential. On first boot BookCars' database is initialised fresh, a unique administrator is created, and the login is written to a root only file. MongoDB runs as a replica set with key file internal authentication and authorization enabled, bound to loopback. Read your administrator login:

sudo cat /root/bookcars-credentials.txt

The file holds your storefront and admin URLs, the administrator email and the administrator password, all unique to this VM.

Step 6: Sign in to the admin panel

Open the admin panel in your browser at http://<vm-ip>:8080/. You are presented with the BookCars sign in screen.

Sign in with the BOOKCARS_ADMIN_EMAIL and BOOKCARS_ADMIN_PASSWORD from the credentials file. You land on the administrator dashboard, where you manage bookings, cars, suppliers, locations and users.

You can confirm the administrator credential works from the command line too. The API returns a signed JSON Web Token for the correct password and rejects a wrong one:

EMAIL=$(sudo grep '^BOOKCARS_ADMIN_EMAIL=' /root/bookcars-credentials.txt | cut -d= -f2-)
PASSWORD=$(sudo grep '^BOOKCARS_ADMIN_PASSWORD=' /root/bookcars-credentials.txt | cut -d= -f2-)
curl -s -X POST http://127.0.0.1/api/sign-in/admin \
  -H 'Content-Type: application/json' \
  -d "{\"email\":\"$EMAIL\",\"password\":\"$PASSWORD\",\"mobile\":true}" | grep -o accessToken

accessToken in the output confirms the round trip succeeded.

Step 7: Explore the customer storefront

Open the storefront at http://<vm-ip>/. This is your public car rental site, where customers search for cars by location and dates and complete a booking.

Step 8: Add suppliers, locations and cars

From the admin panel, populate your catalogue: create suppliers (the rental companies), locations (pick up and drop off points), and cars with their specifications, pricing and availability. The cars view provides rich filters across rating, range, seats, gearbox, fuel policy, mileage and deposit so your customers can find the right vehicle.

Step 9: The runtime stack

Everything is reachable through nginx: the storefront on :80, the admin panel on :8080, and the API's /api and /cdn routes proxied to 127.0.0.1:4002. The image is fully patched with unattended security upgrades enabled, and the first boot service self disables after provisioning per instance state.

curl -s -o /dev/null -w 'storefront :80 -> %{http_code}\n' http://127.0.0.1/
curl -s -o /dev/null -w 'admin :8080  -> %{http_code}\n' http://127.0.0.1:8080/

Step 10: Enable payments and email

Live checkout and transactional email are configured in the backend environment file and, for the front ends, rebuilt into the static bundles. The backend file is /opt/bookcars/backend/.env.

• Stripe or PayPal: set BC_STRIPE_SECRET_KEY (and the storefront's VITE_BC_STRIPE_PUBLISHABLE_KEY), or BC_PAYPAL_CLIENT_ID and BC_PAYPAL_CLIENT_SECRET, then restart the API with sudo systemctl restart bookcars-api.
• SMTP email: set BC_SMTP_HOST, BC_SMTP_PORT, BC_SMTP_USER, BC_SMTP_PASS and BC_SMTP_FROM for booking confirmations and password resets.

The front end payment keys are baked at build time, so after editing the storefront's .env rebuild and redeploy it:

cd /opt/bookcars/frontend && sudo npm run build && sudo cp -rf build/* /var/www/bookcars/frontend/

Step 11: Enable HTTPS

For production, put a domain and a TLS certificate in front of the appliance. Point your domain at the VM's public IP, then use Certbot with the nginx plugin:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

Certbot obtains a certificate and configures nginx to serve the storefront over HTTPS on port 443, renewing automatically.

Managing the services

sudo systemctl status bookcars-api --no-pager
sudo journalctl -u bookcars-api -n 20 --no-pager
sudo systemctl is-active mongod nginx

To follow the API log live, run sudo journalctl -u bookcars-api -f. To restart the API after a configuration change, run sudo systemctl restart bookcars-api.

The API logs to /var/log/bookcars-api.log. MongoDB data lives under /var/lib/mongodb and uploaded images under /var/www/cdn, both on the OS disk.

Support

Every cloudimg deployment includes 24/7 support. If you have any questions about this image, contact the cloudimg support team through the Azure Marketplace listing.