Skip to content
NZ design
Cart 0 items in cart

Getting started

You have a working store. Everything below is what turns it into your store, roughly in the order it makes sense to do it. None of it takes long, and the store keeps working while you go.

1. Create your admin account

Open /admin. There is no account yet, so the first screen asks you to make one. That account is the super admin: it owns the whole back office, the KahunaCart section included.

There is no published password anywhere in this package, and no account is shipped with it. If a login existed before you made one, something is wrong.

2. Your licence is already installed

Your KahunaCart licence was written into user/data/licenses.yaml when you downloaded this package. You can see it, and add others, under Admin → License Manager.

It covers the KahunaCart plugin itself and its four payment providers — Stripe, Polar, PayPal and the dummy provider — which is why they update through the admin like any free plugin. Add-ons sold separately, such as Licenses, Subscriptions and Newsletters, are not covered by it; buy one and install it with bin/gpm install <slug> or from Admin → Plugins, and it appears in the sidebar on the next request.

3. Look around, then place a test order

The catalog is not a mock-up. Eleven products across nine categories, ten attribute definitions, two sales, seventeen reviews, four coupons, a trade price list, sales tax for three US states, VAT for all 27 EU states and the UK, and four delivery zones — all of it is real rows in user/data/kahunacart/db/kahunacart.sqlite, put there before the package was zipped.

So browse the shop, put something in the cart, and check out with Bank Transfer. It is enabled precisely so that a store with no payment keys configured can still reach a receipt. Then look at the same order in the admin under KahunaCart → Store → Orders, and at the mail it sent under Operations → Email log.

Do this before you change anything. Ten minutes spent seeing what a customer sees is the cheapest thing on this page.

4. Put the worker in cron

bin/plugin kahunacart status

That prints what the store thinks about itself: the schema version, the indexes, and when the worker last ran. If the worker has never run, order confirmations, download grants, stock holds, webhook deliveries and every scheduled sweep are queued and waiting forever. It is the single most common cause of "the customer never got their download".

Add it to Grav's scheduler, or straight to cron, every minute:

* * * * * cd /path/to/site && /usr/bin/php bin/plugin kahunacart work >/dev/null 2>&1

Or let Grav's scheduler run it: KahunaCart registers its worker as a scheduler job, so the one cron line bin/grav scheduler --install prints is enough.

5. Choose a payment provider

Under Admin → Plugins, install and enable one of KahunaCart Stripe, KahunaCart Polar or KahunaCart PayPal, then open its settings and put your keys in. Your licence covers all three, so the choice is about which processor you want, not which one you paid for.

Then:

  • Bank Transfer stays enabled until you turn it off in the KahunaCart settings. Keep it if you want to take transfers, and edit its instructions — they are placeholder bank details right now. Turn it off if you do not.
  • KahunaCart Dummy ships disabled and should stay that way on a live store. It approves every payment and takes no money, which is useful while you are testing a checkout and a disaster once real customers can reach it.

6. Make it yours

Three names, three files, and they are not linked to each other:

What Where
Site title, author, meta description user/config/site.yaml, or Admin → Configuration → Site
Storefront brand name, tagline, footer, accent colour user/config/themes/kahuna.yaml, or Admin → Themes → Kahuna
The name on the admin sign-in card and sidebar user/config/admin-next.yaml

Set your currency in the KahunaCart settings, reached from the Settings button in the header above any KahunaCart screen — it is USD here, and it decides how every amount in the database is interpreted, so change it before you have orders rather than after.

Set the From address for outgoing mail under Admin → Plugins → Email. Until you do, order confirmations go out from whatever the server's PHP happens to use, which is usually a mailbox nobody reads and often nothing at all.

7. Clear the sample catalog

When you are ready to put your own products in:

bin/plugin kahunacart seed --purge --zones

That removes exactly what the seeder created — those eleven products, their categories, the attributes, the coupons, the price list, the customer groups, and the tax and shipping zones — and nothing else. It prints the full list and asks before it does anything, it leaves any product you added alone, and it keeps a tag or an attribute your own products are still using.

Then add products under KahunaCart → Catalogue → Products, or import a CSV with bin/plugin kahunacart import if you are coming from another store. The purge takes the tax and shipping zones with it, so write your own back under Setup → Tax and Setup → Shipping — both screens have a preset importer for the common jurisdictions.

8. Read the two hard pages before you take real money

Both ship inside the plugin:

  • user/plugins/kahunacart/docs/hardening.md — what changes on nginx, on Caddy, and behind a load balancer. The one that matters most: the SQLite database is inside the web root. The plugin writes a deny-all .htaccess for it, which covers Apache and nothing else. On nginx or Caddy the file is served like any other static asset until you add a rule, and a .sqlite file over HTTP is your entire customer list in one download. Check it on every environment, staging copies included:

    curl -sI https://your-site.com/user/data/kahunacart/db/kahunacart.sqlite | head -1

    Anything but a 403 or 404 means stop and fix it.

  • user/plugins/kahunacart/docs/going-live.md — the pre-launch checklist, generated from the same checks bin/plugin kahunacart check runs. Run the command, and work down whatever it prints in red.

9. Updates

Updates arrive through Admin → Plugins like everything else, using the licence already in this package. It carries one year of updates and support from the date you bought it; the store keeps working after that, it just stops receiving new versions until you renew.

When you are done with this page, delete it. It is an ordinary Grav page at user/pages/02.about/, it is in your menu, and your customers have no use for it. Put an About page of your own there instead.