Installing It

Access keys, the authenticated Composer repository, composer create-project, and the setup:install flags that matter.

Syntaxbin/magento setup:install --base-url=<url> --db-host=<host> --db-name=<db> --db-user=<user> --db-password=<pw> --search-engine=opensearch --opensearch-host=<host> [--admin-* flags]

Magento is not on Packagist. Its packages come from the authenticated repository repo.magento.com, so an installation starts with keys rather than code.

Keys

Create an access key pair in Commerce Marketplace. The public key is the Composer username and the private key is the password. Composer keeps them in auth.json, either in the project directory or in your global Composer home.

Two steps, not one

composer create-project downloads code and nothing else. No database is touched and there is no store yet. bin/magento setup:install is the step that creates the schema, writes app/etc/env.php and app/etc/config.php, creates the admin user and prints the admin URL.

The flags that matter: --base-url, which needs both the scheme and a trailing slash; --backend-frontname, which is given a random value if you omit it; the --db-* group; the --admin-* group, all five of which are required; --search-engine with --opensearch-host and --opensearch-port; and --use-rewrites=1. --key sets the encryption key and is generated when omitted. Every flag accepts two forms that mean the same thing: --db-host=127.0.0.1 and --db-host 127.0.0.1.

What trips people up

Re-running setup:install does not drop the database unless you pass --cleanup-database, so a second attempt on a half-finished install fails on tables that already exist.

Example

Example · bash
# 1. authenticate Composer against the Magento repository
#    (keys from Commerce Marketplace > Access Keys)
composer global config http-basic.repo.magento.com <public-key> <private-key>

# 2. download the code - no database is touched by this step
composer create-project --repository-url=https://repo.magento.com/ \
    magento/project-community-edition:2.4.9 /var/www/magento

# 3. create the schema, the admin user and app/etc/env.php
cd /var/www/magento
bin/magento setup:install \
    --base-url=http://magento.test/ \
    --backend-frontname=admin \
    --db-host=127.0.0.1 --db-name=magento \
    --db-user=magento --db-password=magento \
    --admin-firstname=Ada --admin-lastname=Lovelace \
    [email protected] \
    --admin-user=ada --admin-password=Str0ngPassw0rd \
    --language=en_GB --currency=GBP --timezone=Europe/London \
    --use-rewrites=1 \
    --search-engine=opensearch \
    --opensearch-host=127.0.0.1 --opensearch-port=9200

# Starting Magento installation:
# ...
# [SUCCESS]: Magento installation complete.
# [SUCCESS]: Magento Admin URI: /admin

When to use it

  • Standing up a local copy of 2.4.9 to follow the rest of this course.
  • Scripting a repeatable install for a CI pipeline that starts from an empty database.
  • Recovering the admin URL and database credentials for a store someone else installed.

More examples

Where the keys are stored

Depending on the Composer version and environment, the global file is at ~/.composer/auth.json or ~/.config/composer/auth.json; composer config --global --list shows which home is in use. Use the per-project form on a build server, where the keys usually arrive as the COMPOSER_AUTH environment variable instead.

Example · bash
# the command above writes this file
cat ~/.composer/auth.json
# {
#     "http-basic": {
#         "repo.magento.com": {
#             "username": "<public-key>",
#             "password": "<private-key>"
#         }
#     }
# }

# or per project, next to composer.json - keep it out of git
cd /var/www/magento
composer config http-basic.repo.magento.com <public-key> <private-key>

What setup:install wrote

This is the file to read when you have forgotten the admin path or need the database credentials, and the file to protect: it holds the encryption key that encrypted values in the database depend on. In 2.4.9 setup:upgrade also removes the deprecated SET NAMES utf8 init statement from the connection block if an older install left one there.

Example · php
<?php
// app/etc/env.php - written by setup:install, never committed to git

return [
    'backend' => [
        'frontName' => 'admin'
    ],
    'crypt' => [
        'key' => '2f6ad1b0e3c54c6d9f1b7a5c8e0d4a37'
    ],
    'db' => [
        'table_prefix' => '',
        'connection' => [
            'default' => [
                'host' => '127.0.0.1',
                'dbname' => 'magento',
                'username' => 'magento',
                'password' => 'magento',
                'active' => '1'
            ]
        ]
    ],
    'x-frame-options' => 'SAMEORIGIN',
    'MAGE_MODE' => 'default',
    'directories' => [
        'document_root_is_pub' => true
    ]
];

The three commands after the installer

A fresh install is in default mode, which caches like production but generates like developer and is the worst of both for local work. Set developer mode first. cron:install adds the crontab entry that indexers, email sending and queue consumers depend on; without it a local store looks broken in ways that have nothing to do with your code.

Example · bash
cd /var/www/magento

bin/magento deploy:mode:set developer
# Enabled developer mode.

bin/magento cron:install
# Crontab has been generated and saved

bin/magento module:status Magento_Catalog
# Magento_Catalog : Module is enabled

Related

m2 requirementsm2 directory structurem2 clim2 dev modesm2 dev sample data

Discussion

  • Be the first to comment on this lesson.