First run

After cloning the repository and filling in .env, run the one-shot setup script to install dependencies, generate the application key, migrate the database, and build the frontend. Then create the first super-admin user to log in.

Running setup

The composer run setup script performs every step needed to go from a fresh clone to a ready-to-run application. Run it once on initial deployment (or on a new bare-metal host without Docker):

composer run setup

This executes the following steps in order:

1. composer install — install PHP dependencies
2. Copy .env.example to .env (skipped if .env already exists)
3. php artisan key:generate — generate the 32-byte APP_KEY
4. php artisan migrate --force — run all database migrations
5. npm install --ignore-scripts — install Node dependencies
6. npm run build — compile frontend assets (tsc && vite build)

Note

composer run setup is designed for bare-metal or CI use. In the Docker Compose stack the entrypoint handles migrations automatically when RUN_MIGRATIONS=true. You do not need to run composer run setup inside a running container.

Caution

php artisan migrate --force runs migrations without prompting, even in production (APP_ENV=production). Ensure your database credentials in .env are correct before running this command.

Creating the first admin user

Marketix has a dedicated Artisan command for creating super-admin users. There is no seeded default admin account — you must create one explicitly.

Command signature

php artisan marketix:create-admin
    {--name=  : The admin display name}
    {--email= : The admin email address}
    {--password= : The admin password (prompted securely if omitted)}
    {--force : Skip the confirmation when promoting an existing user}

Interactive usage (recommended)

Run the command without options and it will prompt you for each value:

php artisan marketix:create-admin

You will be asked for:

1. Name — the admin’s display name
2. Email — the admin’s email address
3. Password — entered securely (input is hidden); confirmed by a second prompt

Non-interactive usage

Pass all values as options for scripted or CI deployments:

php artisan marketix:create-admin \
  --name="Admin" \
  --email="admin@example.com" \
  --password="your-strong-password"

Promoting an existing user

If a user with the given email already exists, the command offers to promote them to super-admin without changing their password:

php artisan marketix:create-admin --email="existing@example.com"
# → User existing@example.com already exists. Promote to super admin? [Yes]

Use --force to skip the confirmation prompt in automated scripts.

Running inside Docker

If you deployed with Docker Compose, run the command against the running app container:

docker compose exec app php artisan marketix:create-admin

First login

1. Open your browser at https://<APP_DOMAIN>.
2. Log in with the credentials you set above.
3. If your account is the only one, you land directly on the admin dashboard. If there are multiple projects, you are taken to the project chooser at /projects, where you can select which project to enter.

The super-admin account has access to the /admin area (Users, Projects, Mailer, Branding, Storage, Activity) in addition to all project dashboards.

Demo data (optional)

For evaluation or staging environments, the marketix:demo:setup command seeds the database with sample users, projects, domains, and short links:

php artisan marketix:demo:setup

Danger

marketix:demo:setup runs migrate:fresh --force, which drops and recreates all tables. Never run this on an instance with production data. It is intended for fresh evaluation instances only.

The command creates three users (admin / john.doe / max.mustermann, all with password password) and two sample projects with domains and short links. Use --force to skip the interactive confirmation.

Setting up GeoIP (recommended)

Click statistics include geographic data (city, country, coordinates) resolved from the visitor’s IP address using the MaxMind GeoLite2-City database. Without this database, redirects still work but the geo columns in Statistics will be empty.

Prerequisites

You need a free MaxMind account and a license key. Sign up at maxmind.com and generate a license key in your account settings. Add it to .env:

MAXMIND_LICENSE_KEY=your_license_key_here

Downloading the database

Run the update command:

php artisan marketix:geoip:update

Inside Docker:

docker compose exec app php artisan marketix:geoip:update

The command downloads the GeoLite2-City tarball (~60 MB), extracts it, and saves the .mmdb file to storage/app/geoip/GeoLite2-City.mmdb. This location is read by the application’s GeoIP resolver at redirect time.

Note

The GeoLite2-City database is updated by MaxMind weekly. Re-run marketix:geoip:update periodically to keep geo data accurate. The Laravel scheduler (scheduler container in Compose) can be used to automate this — check your application’s scheduled tasks for any pre-configured frequency.

Verify the installation

After first login and GeoIP setup, confirm everything is working:

1. Log in as the super-admin and navigate to /admin/users — your user should appear.
2. Create a Project from /admin/projects/create and add yourself as a member.
3. Navigate to the project dashboard and create a test short link.
4. Follow the short link from a browser tab and confirm you are redirected.
5. Return to the project’s Statistics page and confirm a click was recorded.
6. Check that Horizon is running:

docker compose logs horizon

You should see Horizon worker startup output and no error messages.