Skip to content

First Steps

Jump to bottom
MrJSA edited this page Oct 27, 2026 · 3 revisions

After the Installation, work through these steps once, in this order. All settings are in the admin (https://admin.example.com) under Settings; every step saves with its own Save button.

New to the admin? Admin Overview shows where everything is.

Plan about an hour. At the end you place a test order to check that everything works together.

1. Log in and set your password

  1. Open the admin and log in as admin with the initial password from the installation (docker compose logs backend | grep "Initial admin").
  2. Choose your own password (at least 12 characters). Store it in your password manager.

2. Store Identity & Legal

Settings → Store Identity & Legal. These details appear in the shop header, on invoices, in emails and in your legal texts, so fill them in completely.

Field What to enter
Store Display / Trade Name The name customers see, e.g. Example Crafts
Legal Company / Business Name The registered name, e.g. Example Crafts GmbH or your own name
Store Owner / Represented By Owner or managing director
Header Subtitle / Tagline Short line under the shop name (optional)
Street, House Number, Postal Code, City, Country Your business address (required for the legal notice and invoices)
Commercial Register Court and number, e.g. Amtsgericht Berlin HRB 12345 (only if registered)
Customer Support Email Shown to customers and used as reply address
Contact Phone Number Shown in the legal notice

Tax: choose the VAT regime that applies to you:

  • German Kleingewerbe — small business without VAT (§ 19 UStG).
  • Included VAT (Brutto) — prices you enter already contain VAT (usual for selling to consumers).
  • Excluded VAT (Netto) — prices you enter are net; VAT is added at checkout.

Then enter your VAT ID (USt-IdNr.) and/or tax number (Steuernummer), and check Currency Code (e.g. EUR) and Currency Symbol (e.g. €).

Order numbers: keep 10000+ (Ascending) or choose a custom prefix (up to 7 letters) with a date code, e.g. EXC-20261027-….

Logo: upload your logo in Settings → Media Library first, then pick it under Logo URL / Image Path.

3. Email

Settings → Email & Auth Policies. The shop sends order confirmations, invoices, shipping notices, password resets and alerts. Use the SMTP access of your mail provider (you find it in your mail provider's help pages under SMTP).

Field Example
SMTP Host / Server smtp.example-mail.com
SMTP Port 587 (with STARTTLS) or 465 (with SSL/TLS)
Encryption Mode must match the port
SMTP Username / Password Usually your full email address and its password (or an app password)
Sender Email Address Leave empty to send from the SMTP login; otherwise an address of the same mail account
Sender Display Name e.g. Example Crafts

Save, then send a test email to yourself. The type SMTP Connection Test checks the connection; the other types (order confirmation, payment confirmed, shipped, password reset …) show you what customers will receive. If it fails, the exact answer of the mail server is shown — see Troubleshooting.

In the same tab:

  • Require Account at Checkout — on: customers must register; off: guest checkout is allowed.
  • Require Email Verification — new customer accounts must confirm their email address first.
  • Alert recipients — choose which admin accounts receive alerts (e.g. low stock, failed backups).

4. Payment providers

Settings → Payment Providers. You can use Stripe, PayPal or both.

Stripe (cards, Apple Pay, Google Pay, SEPA, Klarna …)

  1. Create an account at stripe.com and complete the business verification.
  2. In the Stripe Dashboard → Developers → API keys copy the publishable key (pk_…) and the secret key (sk_…). Start with the test keys (pk_test_…, sk_test_…); the admin shows TEST keys or LIVE keys. Both keys must be of the same kind.
  3. Paste both keys, set the Label shown at checkout (e.g. Card / Apple Pay / Google Pay) and tick the payment methods you want to offer.
  4. Webhook (recommended, required for SEPA Direct Debit): Stripe Dashboard → Developers → Webhooks → Add endpoint
    • URL: https://shop.example.com/api/v1/payments/stripe/webhook
    • Events: payment_intent.succeeded, payment_intent.payment_failed, checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed
    • Copy the signing secret (whsec_…) into Webhook signing secret.
  5. Apple Pay & Google Pay: click Register domain, then Check status. The buttons only appear on HTTPS, with the registered domain and on supported devices.
  6. Save. When the shop goes live, repeat steps 2 and 4 with the live keys and a live webhook.

PayPal (PayPal account, Pay Later)

  1. Open developer.paypal.com → Apps & Credentials and create a REST app.
  2. Copy Client ID and Secret into the admin and set the label shown at checkout.
  3. Sandbox credentials only work with Sandbox switched on; for real payments switch to the Live tab in PayPal, copy the live credentials and turn Sandbox off.

5. Shipping

Settings → Shipping & Delivery. Shipping costs are built from three parts:

  1. Carrier — e.g. DHL with a Tracking URL Template so customers get a tracking link in the shipping email.
  2. Zones — groups of countries, e.g. Germany, EU, World. Mark one zone as Default / Fallback Zone for all countries you did not list; leave it out if you only ship to the listed countries.
  3. Rates per zone — name, package type, price, estimated delivery time and a weight range in grams (0 as max weight = no limit). Customers see the matching rate and delivery time at checkout.

Tip: Copy to provider / Copy from zone saves typing when several zones have similar rates. For weight-based rates, enter a weight for each product.

6. Legal texts (Germany / EU)

Storefront & Design → Policy CMS (Markdown) contains templates for legal notice (Impressum), terms (AGB), withdrawal policy (Widerrufsbelehrung), privacy policy, shipping policy and cookies.

  • Placeholders such as {{STORE_NAME}}, {{LEGAL_NAME}}, {{COMPANY_ADDRESS}}, {{SUPPORT_EMAIL}} or {{VAT_ID}} are filled in automatically from step 2 — fill in the rest and check the live preview.
  • The templates are a starting point, not legal advice. Have them checked by a lawyer or a legal text service, especially the privacy policy: mention Stripe, PayPal, your mail provider, your hosting provider and GitHub (for backups).

Settings → Shop Features & Legal switches the legally relevant features on: withdrawal button, unchangeable invoices, VAT note and shipping link next to prices, privacy policy link, limits for digital downloads and the fallback delivery time. Every option is explained on the page.

Storefront & Design → Cookie Consent sets up the cookie banner.

Optional features such as product reviews and the newsletter are switched on in Settings → Shop Features & Legal; how to use them is described in Admin Overview.

7. Storefront and catalogue

  1. Products → Categories Tree — create your categories (can be nested).
  2. Products → Products & BOM — add products with images, prices, stock, weight and variants.
  3. Storefront & Design → Hero & Carousels — banners on the home page.
  4. Storefront & Design → Navigation Menus — header and footer menus; link your legal pages in the footer.

8. Admin users

Settings → Admin Users & Access. Give everyone their own account instead of sharing yours:

  • superadmin — always has full access, including updates, domains, backups and users
  • admin and editor — only the admin sections you tick for them (e.g. products and orders)

Add an email address to accounts that should receive alerts.

9. Backups

Settings → Export & Backups — switch on automatic backups to a private GitHub repository. This takes 5 minutes and is described step by step in Backups. Do it now, before the first real order.

10. Test order, then go live

  1. Open the shop and place an order with a test card (Stripe test card 4242 4242 4242 4242, any future date, any CVC) or a PayPal sandbox account, using the test/sandbox credentials from step 4.
  2. Check that you receive the order confirmation and payment confirmation with the invoice PDF.
  3. In the admin under Orders & Slips → All Orders, open the order, set it to shipped with a tracking number and check the shipping email.
  4. Cancel the test order (Cancel Order in the order).
  5. Everything works? Replace the test credentials with the live Stripe keys and live webhook, and switch PayPal from Sandbox to Live (step 4). From now on, payments are real.

Your shop is open. Keep it up to date with Updates.

Home

Getting started

Running the shop

Help & feedback

Clone this wiki locally