Installation

Installing Pepper works like installing WordPress. You upload the files, open your web address and follow the steps in your browser. You don't need the command line.

Before you start

You need:

• A hosting account that meets the Requirements. Most PHP hosts do.
• A web address of its own, for example app.example.com. If your domain already has a website, add a subdomain in your hosting control panel.
• A database. The simplest choice is SQLite, which needs no setup. You can also create an empty MySQL or MariaDB database in your hosting control panel.

Caution: do not install Pepper in a subfolder such as example.com/app. Links, signed quote links, cookies and assets can break there.

Already using Pepper? Don't install it again. Install the update from the dashboard instead.

Upload files

1. Extract the Pepper release zip on your computer.
2. Upload everything inside it to your web address, using your hosting file manager or an FTP program.

Upload the hidden .htaccess files too. Some FTP programs hide them by default.

Run the web installer

Open your web address in a browser. The installer starts.

1. Enter the setup token

The installer first checks that the hosting account is yours.

1. In your hosting file manager, open storage/app/private/installation/setup-token.
2. Copy its contents into Setup token.
3. Click Continue to setup, then finish within 30 minutes.

Keep the token private. If it is older than 24 hours, delete the file and reload the page to get a new one.

2. Requirements

The installer checks your server. When every required check passes, click Configure instance. If a check fails, Common issues explains the fix.

Have a backup from an earlier installation? Choose Import a backup here and follow the browser import steps.

3. Configure

Enter:

• Your business name, Language and region, and time zone. In Time zone, type part of a city name, for example Auckland.
• Your database. Choose SQLite, or enter the MySQL/MariaDB details from your hosting provider. See Database target.
• Your owner account. The password needs at least 8 characters.
• How email is sent. Not sure yet? Choose Log mode and change it later. See Email configuration.

The language-and-region step shows the initial currency and number, date, time and week defaults before installation. For example, English (United Kingdom) starts with GBP and day-first dates; Português (Brasil) starts with BRL.

Your selection initializes the company defaults and your account's display preference. It does not convert any saved amount. Later locale changes leave the company currency unchanged.

If setup is interrupted, retry with the same region and destination. A different region cannot resume that attempt. Keep the existing setup files and follow the displayed recovery instructions.

Click Next step. If something is wrong, a message above the button tells you what to fix.

4. Desk

Choose Where should Pepper open? Everything is selected until you choose another desk.

1. Choose a desk. Choose Bookings for appointments, resources and events, or Work for projects, calendars and documents.
2. If Business type appears, choose an optional match. Venue offers salon, restaurant, shop and studio layouts; Listings offers real estate, Work offers agency and Money offers trades.
3. Inspect the selected desk's pages and Home layout. For Everything, scroll the menu to see Money, Sales, Work and Customer services, with Home, My work and Inbox above them.
4. Click Next step.

A business type names and arranges the selected desk. It keeps that desk selected. Choosing another desk clears a business type that no longer fits.

Every module stays installed. Owners can reach every desk from the top bar. People you invite start with the business choice until you give them other desks. Read Choose and arrange your desks.

5. Install

Review the summary, including Pepper opens at and your chosen desk.

To explore the app, turn on Add demo data. The samples describe Pulse Studio, a small design studio that helps venues, workshops and publishers prepare an opening or an event: customers, leads and deals, quotes and invoices, projects, purchases, files, forms, saved views and boards. Their dates are relative to the day you install: six months of history, work for this week and planned work ahead. Open Projects to follow the client work, or Workload to compare the team’s available, planned and logged time. Leave it off for your real business.

Sample boards include Ideas, a project with linked records, and Client work. Five fictional collaborators have profile photos: Anna Becker, Noah Williams, guest Sam Rivera, accountant Leo Martin and front-desk colleague Lina Vermeer. Employees start in Work, Leo in Accounting and Lina in Venue. Sam can open only Client work. Your owner account keeps its name, password and photo.

Samples also include appointment, stay, workshop and event bookings, six listings, four offer types and workspace plans. The studio logo and artwork are bundled files. Fresh-install public widgets stay closed. Workspace invitations are cancelled; these examples create no customer login or automatic charge.

A separate dedicated demo also includes three active customer businesses with Venue, Listings and Showcase desks, recent visitor activity and service invoices. These active accounts are not added by the buyer installer.

The fictional accounts have random passwords that setup discards. They use example.test addresses, and setup sends no invitations or email. You can deactivate these accounts in People. Updates never add sample people to an existing installation.

Click Install Pepper. When you see Installation complete, sign in with the owner account you just created.

That's it. Each empty screen explains what it will hold and offers the first step.

The installer uses your browser's language when Pepper supports it. To switch, choose a language at the bottom of the page. The company Language and region choice is separate from that browser language. See Localization.

Database target

SQLite stores everything in one private file, storage/database.sqlite. You don't need a database username or password.

MySQL / MariaDB needs the host, port, database name, username and password from your hosting provider. The database must be empty. Supported versions are MySQL 8.4 and MariaDB 10.11, 11.4 and 11.8.

You can switch between them later with a full export and an import into a new installation.

Database check messages

If the installer can't use your database, it shows one of these messages and changes nothing.

The installer never empties or changes a database that already holds data. Use a new, empty database and try again.

Email configuration

Choose how Pepper sends email:

• SMTP: enter the server, port, username, password and encryption from your email provider, such as Gmail, Outlook, Amazon SES or Mailgun.
• Resend: enter your API key from resend.com.
• Log mode: sends nothing yet. Documents you send stay Not emailed. Useful while you test.
• Mailpit: for developers testing on their own computer.

To change email delivery later, see Email delivery.

Failure recovery

If installation fails, Installation failed shows the reason. Fix the cause, then click Try again with the same database and owner email. To change your details, click Back.

If the message says installation stopped while it created the database tables, use a new, empty database, or remove the partial tables only from the empty database you created for this attempt. Never remove existing business data. When in doubt, contact support with the reference shown in the message.

If your browser lost the connection at the end, visit the site again and sign in. Do not run the installer again.

Troubleshooting

See Common issues for blank pages, permission errors, missing extensions, database problems and email delivery issues.

Technical notes

For server administrators and developers. You don't need these for a normal installation.

• Web server: on Apache, the included .htaccess files route requests, even when the host can't point the document root at public/. On Nginx, route requests to public/index.php.
• Writable folders: the application root, storage/ and bootstrap/cache/ must be writable. Public setup requires HTTPS; loopback HTTP works for local development.
• Public widget performance: enable compression for local CSS and JavaScript. See Public widget pages.
• No build step: the release zip already includes its dependencies and compiled assets. All assets are local; nothing loads from a CDN.
• Setup token: stored with owner-only file permissions and never shown in page source, responses or logs.
• Logs: database refusals and setup failures go to storage/logs/laravel.log with a support reference, never with passwords, usernames or hosts. A successful installation adds a log entry and a system.installed audit log entry.
• Retries: a retry keeps the application key and any owner password already written by that attempt. If the private attempt record and its database marker don't match, Pepper refuses further writes.
• Demo installations: DemoSeeder and demo:reset refuse to run. For a public read-only demo, use a separate installation with DEMO_MODE=true, MAIL_MAILER=log and its own APP_URL and database. To build one from a deployment script, see Disposable demo rebuild.

Check installation health

Open Settings > Installation health after setup. Read the result for scheduled work, email, backups, file storage, updates, PHP and the secure address. Each check links to its next step. See Installation health.