Cart 0 Checkout

Page

Installing SmithShop

First install, update packages, shared hosting, VPS setup, permissions, database setup, and common install fixes.

First install package vs update package

  • A first-install package is used for a brand new store. It should include the browser installer so the owner can open install.php, enter database details, create the first admin account, and finish setup.
  • An update package is used after SmithShop is already installed. It is installed from Admin > Updates or by replacing app files manually, and it preserves .env, storage, public/uploads, downloads, backups, logs, and the database.
  • Do not use an update-only package as a fresh install unless the package clearly includes the installer and installation instructions.
  • Do not rerun the installer on a live store unless you intentionally want to wipe or rebuild that store. The storage/installed.lock file protects against accidental reinstall.

Shared hosting or cPanel style install

  • Use this manual path for shared hosting and for servers already managed by cPanel, Plesk, DirectAdmin, CloudPanel, CyberPanel, Hestia, ISPConfig, Virtualmin, or a similar control panel. The automatic VPS script is for a blank unmanaged server only.
  • Before buying hosting, confirm the plan supports PHP 8.0 or newer, MariaDB or MySQL, URL rewriting, scheduled tasks or cron, outbound HTTPS connections, and the required PHP extensions. Static hosting and site-builder-only plans cannot run SmithShop.
  • Create a database and database user from the hosting control panel. Save the database name, username, password, host, and port.
  • Upload the first-install SmithShop zip to the account, extract it into the folder you want to use for the store, and point the domain or subdomain document root to the public folder inside that SmithShop folder.
  • The web root must be the public folder. Do not point the domain at the project root, because .env, storage, backups, downloads, and app code must not be public web files.
  • Make .env, storage, storage/logs, storage/mail, storage/backups, storage/updates, storage/downloads, and public/uploads writable by the PHP/web server user.
  • Open https://your-store-domain/install.php and follow the installer. After installation, remove or block public/install.php.
  • If the hosting provider will not let the domain point to SmithShop's public folder, ask the provider for the safe document-root configuration before installing. Do not expose the whole SmithShop project inside public_html.

VPS Apache or Nginx install

  • Install PHP-FPM, MariaDB/MySQL, and the PHP extensions pdo, pdo_mysql, openssl, json, session, fileinfo, and gd.
  • Create a virtual host with its document root pointed to /path/to/smithshop/public.
  • For Apache, enable rewrite and PHP-FPM proxy handling. For Nginx, pass PHP requests to the correct PHP-FPM socket.
  • Use HTTPS before handling real customer data. Let Certbot or your hosting panel create the SSL certificate.
  • Set APP_ENV=production and set the final HTTPS Site URL in Admin > Settings after installation.

Permissions that matter

  • The app code should not need world-writable permissions. Do not use chmod 777.
  • Only runtime paths need write access: .env during install, storage, storage/logs, storage/mail, storage/backups, storage/updates, storage/downloads, and public/uploads.
  • For browser updates, the PHP/web server user must also be able to overwrite the app code files. If your host keeps code files owned by FTP/cPanel, use the hosting file manager or FTP update method instead.
  • Digital files belong in storage/downloads, not public/uploads, so customers can receive them only through paid order download links.

Common installation problems

  • A 404 on every page usually means the web root is wrong or URL rewriting is not enabled. Confirm the domain points to public and that .htaccess or Nginx rewrite rules are active.
  • A blank page usually means a PHP fatal error. Check the web server error log and confirm the required PHP extensions are installed.
  • Database connection failed means the database name, username, password, host, port, or user grants are wrong.
  • Writable path errors mean .env, storage, or public/uploads cannot be written by PHP. Fix ownership or permissions from the hosting control panel, FTP, or SSH.
  • If Cloudflare shows stale pages during setup, bypass cache for admin, login, cart, checkout, orders, payments, contact, and install.php, or temporarily enable Development Mode.

After installation

  • Log in as the first admin and set store name, support email, Site URL, logo, currency, tax, shipping, payment gateways, SMTP/sendmail, and policies.
  • Place test orders for a physical product, a digital product, a product with variants, and a product with options.
  • Run Admin > Production and resolve launch warnings before taking real orders.
  • Keep a server or hosting-panel backup before major updates. SmithShop browser updates also create a database backup and a file backup before replacing files.