Setup Guide

Setup Guide

This is the one-time setup to get your own private copy running. Plan about 30 minutes. You'll copy and paste a handful of commands — you don't need to understand them.

💡 Do this once, on a computer. After it's done you use the app on your phone and never come back here (unless you want to update it later).

Before you start, have the things in What You Need ready.

---

Step 1 — Make a Cloudflare account

Go to cloudflare.com and sign up (free). Confirm your email. That's all — you don't need to add a website or a credit card.

Step 2 — Get the setup tools on your computer

You need two free tools installed: Node.js and pnpm.

• Install Node.js (LTS version) from nodejs.org.

• Then turn on pnpm by opening a terminal and running:

  corepack enable

A "terminal" is the Command Prompt / PowerShell on Windows, or Terminal on Mac. Search your computer for it.

Step 3 — Download the app

Download the latest stable release (not the code on the main page) from:

Releases page

Download the source .zip of the newest release, unzip it, and open a terminal inside that folder. Then install the app's parts:

pnpm install

Step 4 — Connect to your Cloudflare account

corepack pnpm exec wrangler login

A browser window opens — sign in to Cloudflare and click Allow (do it promptly — it stops waiting after a minute or two).

⚠️ Use corepack pnpm exec wrangler …, not pnpm dlx wrangler …. On newer pnpm the dlx form stops with an ERR_PNPM_IGNORED_BUILDS error and never runs. exec uses the copy that came with the app in Step 3.

Step 5 — Create your storage (once)

These commands create your private database and your receipt-photo storage:

corepack pnpm exec wrangler d1 create ginoos-log-book
corepack pnpm exec wrangler r2 bucket create ginoos-log-book-receipts

The first command prints a database_id — copy it, you need it next.

Step 6 — Paste in your database ID

cp wrangler.toml.example wrangler.toml

Open the new wrangler.toml file in any text editor and paste your database_id from Step 5 where it says to. Save the file.

Step 7 — Build and publish your app

pnpm db:remote
pnpm run deploy

Type pnpm run deploy exactly — run matters. Plain pnpm deploy runs a different built-in command and stops with an ERR_PNPM_INVALID_DEPLOY_TARGET error instead of publishing.

When it finishes, it prints your app's web address (something like https://ginoos-log-book.<your-name>.workers.dev). This is your app.

---

Step 8 — Lock it down (do NOT skip this) 🔒

Right now your app's address is public — anyone with the link could see your financial data. You must add a lock so only you can open it.

This lock is a free Cloudflare feature called Access. First time only: open Zero Trust (https://one.dash.cloudflare.com), pick any team name, and choose the Free plan.

Then protect the app in a few clicks:

1. In your Cloudflare dashboard, go to Workers & Pages and open your app.
2. Open the Access tab → Protect this Worker behind Access.
3. Choose All traffic (this covers your web address and any preview links).
4. Add a policy that allows only your own email: choose Emails and enter just your address (not "Email domain" — that would let in anyone with that email provider).
5. For the sign-in method, pick One-time PIN — Cloudflare emails you a code, no extra setup. (If One-time PIN isn't offered, add it once under Zero Trust → Settings → Authentication → Login methods → Add → One-time PIN.)
6. Save.

Now, when you open your app, Cloudflare asks you to sign in first. It emails a code to your address; only your email can actually get in.

Full security notes are in the project's SECURITY.md file. To check the lock is on, open your app's address in a private/incognito window — you should be stopped at a Cloudflare sign-in screen before the app loads.

Don't be alarmed if a wrong email also sees that sign-in screen and the "we emailed you a code" message — Cloudflare shows it to everyone on purpose, so outsiders can't tell which addresses exist. The difference is only your allowed email actually receives a working code; everyone else is stopped.

---

Step 9 — Put it on your phone

1. On your phone, open your app's web address (sign in when asked).
2. In the browser menu, tap Add to Home Screen.
3. It now behaves like a normal app icon.

Done! Head to Using the App to add your car and start logging.

---

Updating later (optional)

When a new stable release comes out, download it, and from its folder run pnpm db:remote then pnpm run deploy again. Your data stays put — updates never wipe your trips or receipts. See FAQ for backups.