BookCars on AWS 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, and its data directory on a dedicated EBS data volume mounted at /var/lib/mongodb.
• 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 public IP 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, and MongoDB is never exposed to the network.

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, on a dedicated data volume
• 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

Connecting to your instance

Connect over SSH as the default login user for your operating system variant:

ssh ubuntu@<public-ip>

Step 1: Launch the instance

1. Subscribe to the BookCars listing in AWS Marketplace and choose Launch.
2. Pick an instance type with at least 2 vCPUs and 8 GB RAM. The recommended type is m5.large.
3. Under the security group, allow inbound 80 (storefront), 8080 (admin panel) and 22 (SSH) from the addresses you will manage the instance from. Add 443 if you enable HTTPS.
4. Launch, then wait for the instance to reach a running state. First boot provisions the database, generates the per instance secrets and creates your administrator.

You can also launch from the CLI:

aws ec2 run-instances \
  --image-id <bookcars-ami-id> \
  --instance-type m5.large \
  --key-name <your-key> \
  --security-group-ids <sg-with-22-80-8080> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=bookcars}]'

Step 2: 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 3: 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 instance.

Step 4: Sign in to the admin panel

Open the admin panel in your browser at http://<public-ip>:8080/. You are presented with the BookCars sign in screen. There is no default account; you sign in with the unique administrator generated on this instance.

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 5: Explore the customer storefront

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

Step 6: 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 7: 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/

Both endpoints return HTTP 200 once first boot has completed.

Step 8: 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 9: Enable HTTPS

For production, put a domain and a TLS certificate in front of the appliance. Point your domain at the instance'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 on a dedicated, independently resizable EBS data volume, and uploaded images under /var/www/cdn.

Support

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