Installation & Setup Guide

Prepare these items before uploading SmartQR. Having them ready makes setup much faster.

• PHP 8.3 or newer With the extensions: OpenSSL, PDO, Mbstring, Tokenizer, XML, Ctype, JSON, BCMath, and FileInfo.
• Web server Apache (with mod_rewrite enabled) or Nginx.
• Database MySQL 8, MariaDB 10.3+, PostgreSQL 13+, or SQLite.
• Domain or subdomain For example example.com or qr.example.com.
• Hosting panel access You need access to File Manager, database tools, and domain/document-root settings.
• The SmartQR ZIP file Keep it on your computer until installation is confirmed.

The exact labels differ between cPanel, Plesk, and DirectAdmin, but the steps are the same on all hosts.

1

Step 1

Create a project folder and upload the ZIP

In your hosting File Manager, create a dedicated folder for SmartQR — for example /home/username/smartqr. Upload the SmartQR ZIP file into that folder.

2

Step 2

Extract the ZIP file

Select the uploaded ZIP and click Extract. Extract it into the same project folder. Wait until extraction completes.

After extraction, your project folder contains directories like app, bootstrap, resources, and public. Your domain must point to the public subdirectory.

Create a new database and a database user in your hosting panel. Assign that user to the database with full permissions.

Once upload and domain setup are complete, open your domain in a browser. SmartQR may automatically install Composer dependencies first — that is normal.

1

Installer step 1

Check the requirements screen

Every item should show Ready. If you see Fix needed, resolve that item before continuing.

2

Installer step 2

Enter your site details

• Site title — the name of your website or business.
• App URL — the full address, e.g. https://example.com. No trailing slash.
• Site description — a short sentence about your service. You can change it later.

3

Installer step 3

Enter your database details

Type the exact values from your hosting panel. If your host shows a prefixed database name, use the full prefixed value.

4

Installer step 4

Create your admin account

This is the first account used to manage the entire platform. Save the email address and password somewhere safe.

5

Finish

Click Install SmartQR and wait

SmartQR writes configuration, connects to the database, runs migrations, seeds starter content, creates your admin user, and activates the theme.

If the installer shows an error

Read the message carefully. The most common causes are wrong database details, the wrong document root, or directories that are not writable by the web server.

SmartQR includes starter data so the dashboard is not empty. Before launching publicly, replace the starter content with your own.

This section is for the platform owner. It covers the most important post-install tasks: billing configuration, plan creation, and launch preparation.

If you use Stripe, collect these three values from your Stripe dashboard and save them in Admin → Setup → Billing.

• Publishable key — from Stripe → Developers → API keys.
• Secret key — from Stripe → Developers → API keys.
• Webhook signing secret — from the Stripe webhook endpoint you create for SmartQR.

If you use Paddle, start in Sandbox mode while testing and switch to Production only when you are ready to go live.

• Seller / Vendor ID — from Paddle → Developer Tools → Authentication.
• API key — from the same Authentication area.
• Client-side token — used for the front-end checkout flow.
• Webhook secret — from the Paddle notification destination you create for SmartQR.

SmartQR uses Wave plans and roles together. A plan controls billing and pricing. The linked role controls what a subscriber can access. SmartQR adds extra per-plan limits for QR-related features.

Always test billing end-to-end before opening your site to the public.

• Subscribe with a test card or sandbox checkout.
• Confirm the user receives the correct plan and role.
• Confirm SmartQR feature limits match the plan.
• Test upgrading and downgrading between plans.
• Test cancellation and failed-payment behavior.
• Verify webhook events arrive successfully in your provider dashboard.

SmartQR lets you enable supported social providers from the admin area without editing .env. This section is for site owners and admins who want users to sign in with services like Google or GitHub.

After billing and plans are configured, review the remaining tabs in Admin → Setup.

SmartQR lets your users connect branded custom domains. If you run Caddy with on-demand TLS, you can also let Caddy issue SSL certificates automatically after each domain has been verified inside SmartQR.

{
    on_demand_tls {
        ask https://your-smartqr-domain.com/domains/caddy/ask
    }
}

https:// {
    tls {
        on_demand
    }
}

When plugin management is enabled for your installation, the Plugins page lets admins upload optional plugin ZIPs and activate them from the dashboard. Developer-level enable/disable instructions live in the project README, not in this admin guide.

SmartQR includes an admin update flow for verifying your purchase code, checking the latest release, downloading the update package from your remote server, and running the final migration tasks.

Go to QR Codes in the dashboard, click Create, choose the QR type, enter the destination, and save.

Open Short Links, add the destination URL, and optionally set a custom slug so the link is easy to share.

• Name — optional label for the dashboard.
• Destination URL — the page visitors should reach.
• Custom slug — optional. If left empty, SmartQR generates a random short slug.

Open Landing Pages to create a promotional, event, product, or link-in-bio page. Use the visual editor to add sections, buttons, images, and content blocks.

Open Analytics to see which QR codes and short links are performing best. Use this to measure campaigns and decide what to improve.

Campaigns let you group related QR codes, short links, landing pages, and reports together — for example, one campaign for a restaurant menu, another for an event, and another for a product launch.

• Check the App URL — make sure it matches the real domain visitors will use.
• Test a QR code on a phone — confirm the redirect works and analytics count increases.
• Review branding — logo, colors, site title, and descriptions all replaced.
• Verify billing and limits — provider, webhook, plans, roles, and feature limits match what you are selling.
• Remove demo content — replace demo blog posts, sample pages, and placeholder text.
• Keep a backup — download a backup of files and database once everything is working.

Main software and libraries used in this SmartQR installation.

• Laravel — the main PHP application framework.
• Filament — the admin panel framework.
• Livewire — reactive server-driven UI components.
• Wave by DevDojo — the SaaS starter foundation SmartQR is built on.
• Tailwind CSS — utility-first styling for the frontend and admin UI.
• Alpine.js — lightweight frontend interactions.
• GrapesJS — the landing page builder/editor.
• Stripe — supported billing provider.
• Paddle — supported billing provider.