Installation

Five minutes, no terminal. Extract the package into your domain root, open a browser, and the installer wizard walks you through the rest. Composer dependencies and the front-end build ship pre-installed — you never run composer install or npm run build.

1 · Extract the package

Download kodmail-installer-v1.1.0.zip from your marketplace receipt and extract it directly into your domain root or project folder. The archive contains the project files at the root level — no wrapper folder — so the contents land exactly where the webserver expects them.

2 · Create a database

Using phpMyAdmin, Adminer, or your hosting panel:

1. Create a new database. Recommended name = kodmail, collation = utf8mb4.
2. Note the database name, username, and password — you'll paste them into the wizard.

3 · Open your site URL

Visit the URL from the table above. KodMail detects this is a first run and automatically redirects to /install.

4 · Complete the installer wizard

The wizard collects three pieces of input across seven short steps:

• Database credentials
• Owner admin name, email, and password
• (Optional) Marketplace purchase code — click Skip for now to activate later from /admin/license

The Install step then runs automatically:

• Writes .env with your database credentials
• Runs migrations + seeds the production defaults (roles, locales, currencies, notification events)
• Indexes the UI translation catalog
• Creates the owner admin account
• Syncs license state, writes the install lock, and signs you in

Each task ticks live on a checklist so you can watch progress.

Works two ways: public/ rooted, or project rooted

The Laravel-standard layout puts the web entry point at public/index.php, which works best when your webserver's document root points at the public/ subfolder. On cheap shared hosts and some Plesk setups, that root change isn't always possible. KodMail ships two entry paths so both setups work without editing a single file:

Fresh-upload redirect — how it works

The very first URL the buyer hits after unzipping the package — whether that is /, /admin, /lists, or any other path — gets automatically redirected to /install. There is no way to "land somewhere broken" on a fresh install. The redirect stays in effect until the wizard finishes and writes storage/installed.lock; from that moment on, the redirect retires and every URL routes normally.

This is implemented by the EnsureInstalled middleware which runs at the very top of the request stack, before any other code touches the request. The middleware exempts the install wizard itself, the /up health endpoint, and a few static asset paths (/build/, /images/, /fonts/, /favicon.ico, /robots.txt) so monitoring tools and static caches keep working while the wizard is pending.

The 7 wizard steps

1. Welcome. Brand splash + Get-started button.
2. Requirements. Live check of PHP version, required extensions, writable directories, and optional bonuses (Redis, ImageMagick). Red entries must be fixed before continuing; yellow warnings are nice-to-have.
3. License. Paste your marketplace purchase code, or click Skip for now and add it later under Admin → License.
4. Database. Host, port, database name, username, password. KodMail tests the connection live, then stores the credentials in the session — nothing is written to disk yet.
5. Admin. Create the owner admin — name, email, password. Stored in the session alongside the database credentials until the next step actually runs the install.
6. Install (live progress). Single screen with a checklist of nine setup steps:
   1. Write .env with your database credentials
   2. Connect to the database
   3. Run migrations
   4. Seed core data (roles, customer groups, default settings)
   5. Install languages (10 default locales)
   6. Index UI strings (build the translation catalog)
   7. Create the owner account
   8. Sync license state (grace window or activation)
   9. Finalize installation (write the install lock + activity log)
   Each step emits a server-sent-event as it completes so the checklist ticks live. Total run time is 15-45 seconds depending on the host.
7. Finish. Success screen with Continue button. Click it and you land at /admin/login with your email pre-filled — type your password, you're in.

Refreshing the page mid-wizard never loses your work — every collected value lives in the session, so the buyer can close the tab, come back, and pick up where they left off.

cPanel / Plesk shared hosting walkthrough

1. In cPanel, open MySQL Databases. Create a fresh database + user. Grant the user All Privileges on that database. Save the database name, username, and password.
2. Open File Manager, navigate to public_html/, and use Upload to send kodmail-installer-v1.1.0.zip.
3. Right-click the uploaded ZIP and choose Extract. The Laravel project files (app/, bootstrap/, public/, vendor/, etc.) land directly inside public_html/.
4. If your hosting allows a per-domain document-root selector (most modern cPanel hosts), point the domain at public_html/public/ and skip to step 5.
   
   If your hosting forces serving from public_html/ directly, restructure the upload so the static entry point sits at the root. The shipped layout already supports this — the project-root index.php forwarder + .htaccess handle routing automatically. No file edits required.
   
   If you prefer the explicit Laravel separation, move the project files into a kodmail/ subfolder and hoist public/'s contents to public_html/:

   public_html/
   ├── index.php          ← from kodmail/public/
   ├── .htaccess          ← from kodmail/public/
   ├── build/             ← from kodmail/public/
   ├── favicon.ico
   ├── images/
   ├── robots.txt
   └── kodmail/
       ├── app/
       ├── bootstrap/
       ├── config/
       ├── database/
       ├── resources/
       ├── routes/
       ├── storage/
       ├── vendor/
       ├── artisan
       └── ...

   Then edit public_html/index.php to reference the parent paths:

   require __DIR__.'/kodmail/vendor/autoload.php';
   
   $app = require_once __DIR__.'/kodmail/bootstrap/app.php';

5. Browse to your domain. The installer wizard runs — complete the 7 short steps from the start of this page.
6. Cron: cPanel → Cron Jobs → add one entry:

   * * * * * cd /home/USERNAME/public_html && php artisan schedule:run >> /dev/null 2>&1

   Replace USERNAME + the path with your actual values. schedule:run internally drains the queue, so a Supervisor-managed worker is not required on shared hosting.

VPS / dedicated server walkthrough

Same install path — extract, browse, wizard — with the nginx and Apache configs below for your virtual host.

# Unpack directly into the webroot (no kodmail/ wrapper folder).
mkdir -p /var/www/kodmail
cd /var/www/kodmail
unzip /tmp/kodmail-installer-v1.1.0.zip

# File permissions
chown -R www-data:www-data storage bootstrap/cache
chmod -R 775 storage bootstrap/cache

# Configure the nginx vhost (sample below). Point its root at /var/www/kodmail/public.
# Reload nginx — then visit https://your-domain.com/ and the wizard runs.

# After the wizard finishes, schedule cron:
crontab -e
# add a single line:
* * * * * cd /var/www/kodmail && php artisan schedule:run >> /dev/null 2>&1

Nginx config (Path C)

server {
    listen 443 ssl http2;
    server_name app.example.com;

    root /var/www/kodmail/public;
    index index.php;

    ssl_certificate     /etc/letsencrypt/live/app.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;

    client_max_body_size 25M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
    }

    location ~ /\.(?!well-known).* { deny all; }
}

Apache config (VPS)

<VirtualHost *:443>
    ServerName app.example.com
    DocumentRoot /var/www/kodmail/public
    SSLEngine on
    SSLCertificateFile    /etc/letsencrypt/live/app.example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/app.example.com/privkey.pem

    <Directory /var/www/kodmail/public>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

File-permission cheat sheet

Upgrading from an older release

See the dedicated Updating guide for the one-click Admin → Updates → Apply update flow (recommended), the command-line alternative, env-key backfill behaviour, licence re-verification, and rollback steps.

Hacking on the source

If you're modifying KodMail's source — adding fields, custom controllers, theme tweaks — these are the only commands you need beyond the buyer install:

# Pull PHP dependencies (dev included)
composer install

# Pull front-end dependencies + start the dev server
npm install
npm run dev

# Or produce a fresh production build
npm run build

# Re-run migrations after editing one
php artisan migrate

# Tail the live request log
tail -f storage/logs/laravel.log

The dev tree ships with tests/ and phpunit.xml when you check it out from the source repo — both are stripped from the buyer release.