AutoCom Docs

Installation Wizard

The Installation Wizard guides you through the initial setup of Auto Commerce. It detects your environment, verifies prerequisites, provisions the database, seeds default data, and creates your first organization and admin account -- all from a browser-based interface.

How Installation Detection Works

Before the wizard is ever shown, the backend decides whether the application is already installed by checking two things, in order:

  1. Marker file -- the fastest check. If storage/.installed exists, the app is considered installed.
  2. Database fallback -- if the marker file is absent, the backend checks whether the users and tenants tables both exist and contain at least one row each. If so, the app is treated as installed even without the marker file.

When the app is installed, all /api/v1/install/* routes return a 403 response with {"message": "Application is already installed", "redirect": "/login"}. The frontend detects this and redirects you to the login page.

When the app is not installed, visiting any page on the frontend redirects you to /install, where the wizard begins.

Accessing the Wizard

Navigate to your Auto Commerce URL (for example http://localhost:3000 for a Docker setup). If the application has not been configured yet, you are automatically redirected to the wizard at /install.

The wizard calls GET /api/v1/install/status on load. The response includes:

  • installed -- boolean indicating whether setup is already complete
  • current_step -- the step number the wizard should resume from (1-4)
  • steps -- status of each step (completed or pending)

This means the wizard is resumable. If you close the browser mid-setup, reopening the wizard picks up where you left off.

Step 1: Requirements Check

The wizard calls GET /api/v1/install/check-requirements and verifies every prerequisite before allowing you to proceed.

Checks performed:

Check What is validated Pass criteria
PHP version Runtime version 8.2.0 or higher
PHP extensions pdo, pdo_pgsql/pdo_mysql, mbstring, openssl, tokenizer, xml, ctype, json, bcmath, redis, gd All listed extensions loaded
Database connection Connects to the database using credentials in .env Successful connection and query
Redis connection Connects to Redis using credentials in .env Successful PING
Directory permissions storage/ and bootstrap/cache/ Writable by the web server process

Each check shows a green checkmark or a red cross. If any check fails, the Next button is disabled and a clear error message explains what needs to be fixed.

Common failures and fixes:

Failure Likely cause Fix
PHP extension missing Extension not installed or not enabled in php.ini Install the extension (apt install php8.2-redis, etc.) and restart PHP-FPM
Database connection failed Wrong credentials in .env, or the database server is not running Verify DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD in backend/.env
Redis connection failed Redis is not running, wrong host/port, or a password mismatch Check REDIS_HOST, REDIS_PORT, REDIS_PASSWORD in backend/.env; ensure the Redis service is up
Permission denied The web server user (www-data) cannot write to storage/ Run chmod -R 775 storage/ bootstrap/cache/ and chown -R www-data:www-data storage/ bootstrap/cache/

After fixing issues, click Re-check to run all checks again. You do not need to refresh the page.

Step 2: Database Setup

Once requirements pass, the wizard provisions your database by calling POST /api/v1/install/setup-database.

Actions performed (in order):

  1. Run all migrations -- creates the complete database schema (system tables and tenant tables).
  2. Generate Passport encryption keys -- creates the RSA key pair used to sign OAuth access tokens (storage/oauth-private.key and storage/oauth-public.key).
  3. Create the personal access client -- registers a first-party OAuth client so the API can issue tokens.

This step typically takes 10-30 seconds depending on your database server speed.

If this step fails:

  • The most common cause is a database permission issue (the database user cannot create tables). Ensure the user in .env has full DDL privileges on the target database.
  • If you see a "table already exists" error, the database may contain leftover tables from a previous attempt. Drop and recreate the database, then retry.
  • Network timeouts can occur if the database is on a remote server with high latency. The wizard will show the specific error message from the migration runner.

You can safely click Retry to re-run this step. Migrations are idempotent -- already-applied migrations are skipped.

Step 3: Initial Data (Seeding)

The wizard seeds essential configuration data by calling POST /api/v1/install/seed-data. This gives you a complete RBAC system and module configuration out of the box.

Data seeded:

Category Details
Roles 5 default roles: Owner, Admin, Manager, Agent, Viewer
Permissions 68 granular permissions across 12 categories (orders, products, customers, settings, etc.)
Modules Default module configurations read from each module's module.json
Settings System-wide default settings (currency, timezone, etc.)

If this step fails:

  • The most likely cause is that Step 2 did not complete successfully. Go back and verify the database schema is in place.
  • Seeding is safe to retry. The seeders use "create or update" logic, so running them twice does not produce duplicates.

Step 4: Create Owner Account

The final step creates your first organization (tenant) and admin user account.

Required fields:

Field Validation rules Notes
Organization Name Required, max 255 characters The display name shown in the UI (e.g. "Acme Corp")
Organization ID (slug) Required, lowercase letters/numbers/hyphens only, max 50 characters, must be unique Used in URLs and internal references (e.g. acme-corp). Cannot be changed later.
Admin Name Required, max 255 characters Your full name
Email Required, valid email format, must be unique Used for login
Password Required, minimum 8 characters Stored as a bcrypt hash
Confirm Password Required, must match Password Client-side and server-side validation

Validation runs both on the client (instant feedback) and on the server (when you submit). If the organization ID is already taken or the email is already registered, you will see a specific error message next to the field.

What the wizard creates on submission:

  1. A new User record with the Owner role
  2. A new Tenant (organization) record
  3. A TenantUser link associating the user with the tenant as Owner
  4. A tenant-specific database schema with its own migrations applied

Completion

After the wizard finishes Step 4 successfully, it calls an internal markAsInstalled() method that writes a JSON file to storage/.installed containing:

{
  "installed_at": "2026-03-21T12:00:00.000000Z",
  "version": "1.0.0"
}

You will see a confirmation screen displaying:

  • Your organization name and ID
  • A Go to Login button

Click the button, then log in with the email and password you created to access your dashboard.

What Happens Next?

After installation, the recommended post-setup steps are:

  1. Enable Two-Factor Authentication -- Go to Settings and enable 2FA on your admin account for security.
  2. Invite Team Members -- Add users and assign them the appropriate roles (Admin, Manager, Agent, Viewer).
  3. Configure Integrations -- Connect your e-commerce platforms (Shopify, etc.), shipping providers, and communication channels from the Modules page.
  4. Verify Queue Worker -- Background jobs (order sync, notifications, etc.) require a running queue worker. Docker and Kubernetes setups handle this automatically. For manual installs, confirm the autocom-queue systemd service is active.
  5. Set Up Backups -- Configure automated database and file backups appropriate for your hosting environment.

Re-running the Wizard

The wizard is designed to run only once. After successful completion, the storage/.installed marker file prevents the wizard routes from being accessed.

Using the Artisan Command (Recommended)

The safest way to reset is the built-in Artisan command:

php artisan install:reset

This command interactively:

  • Drops and recreates the database
  • Deletes the storage/.installed file
  • Clears the app.installed cache key
  • Clears the installed row from the settings table (if present)
  • Re-seeds essential data

In a Docker environment, prefix with the container exec:

docker compose exec app php artisan install:reset

Manual Reset

If you prefer to reset manually:

  1. Delete the marker file: rm storage/.installed
  2. Drop and recreate the database (e.g. DROP DATABASE autocom; CREATE DATABASE autocom;)
  3. Clear the Redis cache: redis-cli FLUSHDB
  4. Visit your Auto Commerce URL -- you will be redirected to the wizard

Warning: Both methods destroy all data (users, tenants, orders, products, etc.). Only use this on a fresh installation or for development purposes. In production, take a database backup first.

Why Would You Re-run the Wizard?

Common reasons include:

  • A failed or interrupted first installation
  • Resetting a development or staging environment to a clean state
  • Switching database engines (e.g. MySQL to PostgreSQL)
  • Testing the onboarding flow itself

Troubleshooting

If the wizard fails at any step or behaves unexpectedly, check the following:

  • Laravel log: storage/logs/laravel.log contains detailed error output from the backend.
  • Browser console: Network errors or JavaScript exceptions may indicate a misconfigured NEXT_PUBLIC_API_URL.
  • Docker logs: docker compose logs -f app shows real-time backend output.
  • Redis connectivity: The wizard and middleware both cache installation state. If Redis is unreachable, detection may behave inconsistently.

For more issues, see the Troubleshooting guide.