First-Time Setup
Craft has a built-in setup wizard that streamlines configuration of your database connection, the creation of your first user account, and basic configuration of the default site.
Composer will launch the setup wizard automatically when creating a new project, but you can start it manually from your browser or by running:
php craft setup
This will walk you through three steps:
- Establishing a Database Connection;
- Creating your first User;
- Setting a Site name and base URL;
Craft then runs the installation “migration” which is responsible for creating the required database tables or “schema” and writing out (or applying) project config data.
For each option, you can provide your own value or accept the [default] (presented inside square brackets), and press Enter to confirm. If at any stage Craft is unable to move forward, it will present an error and prompt for new input. You can exit setup by pressing Control + C.
Database #
The following values tell Craft how to connect to your database server. Each tool and platform will be different! Refer to the setup instructions for your development environment if you get stuck.
- Driver: One of
mysql(MySQL or MariaDB) orpgsql(Postgres). - Hostname: The hostname or IP address of the database server.
- Port: The port the database server is listening for connections on.
- User: Username that Craft will use to connect.
- Password: Password for the database user.
- Name: Name of the database to use, accessible to the provided user.
- Table prefix: Optional. Leave blank unless you anticipate running multiple Craft installs off of a single database.
These values will be added to your .env file automatically, and can be tweaked or supplemented with other database options, if necessary.
If Craft has enough information to connect to a database at the beginning of setup, it will skip this step!
Your First User #
Craft will help set up an admin user so you can log in to the control panel as soon as installation completes.
- Username: Admin user’s login name. You will not be asked for this when the
useEmailAsUsernamesetting istrue. - Email: A valid email address for the admin user. This will also be used as the “from” address when Craft sends an email.
- Password: Type and confirm the admin’s password.
Set a strong password now, especially if you intend to seed a staging or production site with your development database.
Site Settings #
The last step in setup is to choose some system and default site settings:
- System Name: Set a name for the site. This is also applied as the “system name” (visible throughout the control panel), and the “from” name when sending emails. These can be changed individually, later.
- Base URL: How will you access the site in your browser?
- Language: What will be the primary language for the site?
GUI #
First-time Craft users may find that the graphical installation wizard provides a friendlier way of troubleshooting initial configuration and connectivity issues. You’ll also get immediate feedback as to whether Craft is accessible via HTTP on your local machine!
The Craft 4 setup wizard welcome screen.
Accessing the installation GUI depends largely on your local development environment—but whatever hostname the site lives at can be appended with /admin/install. For example:
- Using the built-in PHP server or running
php craft servewould mean the admin is available athttp://localhost:8080/admin/install - With DDEV, you might go to
https://my-craft-project.ddev.site/admin/install
Whether you set up Craft from the command line or GUI, you will be asked for the same information.
Running the installer from the GUI often means that Craft is constrained by a more conservative max_execution_time setting for HTTP requests. In some situations, the script may be halted prematurely, leaving you with a partial installation. If you run into issues, try increasing max_execution_time or use the command line.