---
url: /guide/installation.md
description: >-
  Install Media Library Pro from its private Composer repository with your
  licence key, run the installer, register the plugin and publish the assets.
---

# Installation

Media Library Pro is a paid package served from a private Composer repository. Your purchase email holds a licence key; your username is the email you bought with.

## Add the repository

```bash
composer config repositories.media-library composer https://packages.hoceine.com
```

## Add your licence

```bash
composer config http-basic.packages.hoceine.com you@example.com YOUR-LICENCE-KEY
```

This writes to the project's `auth.json`. Keep that file out of git, or add `--global` to store the credentials once for every project on your machine.

## Require the package

```bash
composer require hoceineel/filament-media-library-pro
```

## Run the installer

```bash
php artisan media-library:install
```

The installer does five things:

1. Publishes `config/filament-media-library.php`.
2. Publishes Spatie's `config/media-library.php` if you do not have one yet.
3. Publishes Spatie's `create_media_table` migration if your app has none yet.
4. Asks `Run the migrations now?` and runs `php artisan migrate` if you accept. The library's own tables load from the package, so they are migrated with the rest.
5. Runs `storage:link` when a `public` disk exists and `public/storage` does not.

It finishes by printing the next steps. Pass `--force` to overwrite a config file you published earlier. In a script, add `--no-interaction` so the migration prompt takes its default and does not wait for input.

::: tip Custom key types
If your users or tenants use UUID or ULID keys, set `key_types` in the published config **before** you migrate. Answer `no` to the migration prompt, edit the config, then run `php artisan migrate`.
:::

## Register the plugin

Add the plugin to your panel provider:

```php
use Hoceineel\FilamentMediaLibrary\FilamentMediaLibraryPlugin;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(
            FilamentMediaLibraryPlugin::make()
                ->navigationGroup('Content')
                ->navigationCountBadge()
        );
}
```

This adds the **Media library** page to the panel at `/media-library` under your panel path. If the panel uses Filament tenancy, the library scopes itself to the current tenant with no extra call. For stancl/tenancy or your own tenant lookup, add `->tenancy()` and `->resolveTenantUsing()`. See [Tenancy](/guide/tenancy) and the [plugin reference](/reference/plugin).

## Publish the assets

```bash
php artisan filament:assets
```

Run this again after every update.

## Run a queue worker

Thumbnails are generated while the upload request runs, so new files appear at once. Larger conversions, such as the `preview` size, are queued. Keep a worker running:

```bash
php artisan queue:work
```

## Schedule the cleanup

In `routes/console.php`:

```php
use Illuminate\Support\Facades\Schedule;

Schedule::command('media-library:prune')->daily();
```

The command deletes trash older than 30 days and abandoned upload chunks. See [Commands](/reference/commands).

## Check it works

1. Open the panel and click **Media library** in the navigation.
2. Drop an image onto the page. It should upload and open in the details panel.
3. Run `php artisan route:list --name=media-library` and confirm the upload routes are listed.

If a thumbnail stays blank, check that the queue worker is running and that `storage:link` has been run. For more, see [Troubleshooting](/reference/troubleshooting). To build your first form field, continue with the [Quick Start](/guide/quick-start).

## Deploying

Servers and CI need the same credentials. Either commit nothing and set them per environment:

```bash
composer config --global http-basic.packages.hoceine.com you@example.com YOUR-LICENCE-KEY
```

or provide them as JSON in the `COMPOSER_AUTH` environment variable:

```bash
COMPOSER_AUTH='{"http-basic":{"packages.hoceine.com":{"username":"you@example.com","password":"YOUR-LICENCE-KEY"}}}'
```

On Laravel Forge, add them in the server's or site's Composer package authentication settings. After each deploy, run `php artisan migrate --force` and `php artisan filament:assets`, and restart your queue workers.

## Updates

Your licence includes updates for its update window. Releases published after the window ends stay hidden until you renew; versions you already have keep installing.

## Publishing files

```bash
php artisan vendor:publish --tag=filament-media-library-config
php artisan vendor:publish --tag=filament-media-library-translations
php artisan vendor:publish --tag=filament-media-library-views
```

English and Arabic ship in the box. See [Translations](/reference/translations).