Installation / Composer / Creating a new project
Note: You are currently reading the documentation for Bolt 3.7. Looking for the documentation for Bolt 5.2 instead?
If you are starting a new project from scratch, then we've made this very
simple, and flexible. Bolt's Composer based installs can be performed using
either composer create-project
(recommended), or building your own
composer.json
and path configuration file for more advanced control.
Composer create-project
installs can be run interactively or fully automatic.
In the first case, the installer will prompt for configuration options. With
the automatic mode, the installer will not prompt for choices, but rather use
default configuration options or options taken from environment variables.
An example of the process is shown here:
Create Project¶
Interactive Install¶
To start an interactive install, navigate to the parent directory of your desired project (site), and run the following from a command line:
composer create-project bolt/composer-install:3.7.x <MYPROJECT> --prefer-dist
NOTE: Change <MYPROJECT>
to the name of your project before running the
installer.
The install process will ask you some questions about your required install strategy, you can install Bolt inside a single directory, or you can install the public assets inside a public directory and keep the application code outside the web root.
Tip: Always run composer update
after doing the initial setup. This ensures you that you're running the
latest versions of packages, suitable for your platform.
Automated Install¶
To start an automated install, navigate to the parent directory of your desired project (site), and run either of the following commands depending on what options you desire.
Default Options¶
To simply use default directory locations, you just apply the --no-interaction
parameter to the composer create-project
command, e.g.
composer create-project bolt/composer-install:3.7.x <MYPROJECT> --prefer-dist --no-interaction
NOTE: Change <MYPROJECT>
to the name of your project before running the installer.
Customised Options¶
If you want an automated install with customised configuration options, you can set any, or all, of the following variables and the installer will use them:
BOLT_DIR_MODE
— An octal UNIX permission value, e.g.0775
,0755
,0750
(default:0775
)BOLT_WEB_DIR
— Root web directory name (default:public
)BOLT_THEME_DIR
— Theme directory name (default:theme
)BOLT_FILES_DIR
— Files directory name (default:files
)BOLT_CONFIG_DIR
— Configuration files directory name (default:app/config
)BOLT_DATABASE_DIR
— Database directory name (default:app/database
)BOLT_CACHE_DIR
— Cache directory name (default:app/cache
)
An example with all options set would look like:
env BOLT_DIR_MODE=0755 BOLT_WEB_DIR=my_public_dir BOLT_THEME_DIR=my_theme_dir \
BOLT_FILES_DIR=my_files_dir BOLT_CONFIG_DIR=my_config_dir \
BOLT_DATABASE_DIR=my_database_dir BOLT_CACHE_DIR=my_cache_dir \
composer create-project bolt/composer-install:3.7.x <MYPROJECT> \
--prefer-dist --no-interaction
NOTE: Change <MYPROJECT>
to the name of your project before running the installer.
Initialise a Project¶
For complete flexibility over the installation of your Bolt site, you can create
your own composer.json
file, and path configuration file.
$ mkdir example.com
$ cd example.com
Configuration File¶
This is a very advanced option, see Customising Bootstrapping for more details.
Composer JSON File¶
You will need to create a composer.json
file with the following keys at a
minimum:
{
"require": {
"bolt/bolt": "^3.7"
},
"minimum-stability": "beta",
"prefer-stable": true,
"scripts": {
"post-install-cmd": [
"Bolt\\Composer\\ScriptHandler::installAssets"
],
"post-update-cmd": [
"Bolt\\Composer\\ScriptHandler::installAssets"
],
"post-create-project-cmd": [
"Bolt\\Composer\\ScriptHandler::configureProject",
"Bolt\\Composer\\ScriptHandler::installThemesAndFiles",
"nut extensions:setup"
]
}
}
Required Folders¶
Run the following commands to create the required folders. If you defined a
different folder structure in .bolt.yml
or .bolt.php
, you have to adjust the
commands to fit your own folder structure.
mkdir -p app/cache
mkdir -p app/config
mkdir -p app/database
mkdir -p public/theme
mkdir -p public/files
mkdir -p public/bolt-public/view
mkdir -p public/thumbs
mkdir -p public/extensions
mkdir -p extensions
Finally run Composer to install the required libraries and configure the installation:
composer install --no-scripts
composer run-script post-create-project-cmd
composer run-script post-install-cmd
Permissions¶
Bolt needs to be able to write data to a number of folders. For example the
cache/
folder, and the files/
folder where uploaded images and other files
will be saved.
Generally, servers should be fine with the default permissions. If your server needs to have the permissions set manually, you'll immediately notice when opening your new install in a browser window, because you will greeted by an error, and the message that you should fix this. If this happens, and you require guidance on setting up permissions, see our File System Permissions page.
Finishing Set-up¶
After you've done this, skip to the section Setting up Bolt.
Deploying to Different PHP Versions¶
If you are developing on versions of PHP such as PHP 7, but deploying to hosts running PHP 5, you can run into problems with libraries that use PHP functionality not available in earlier releases.
A common example are the Doctrine libraries, as the project doesn't follow strict semantic versioning for PHP release versions.
If you need to prepare a Composer based install for a specific PHP version, add
the following to the site's root composer.json
file:
"config": {
"platform": {
"php": "5.5"
}
}
This lets you fake platform packages (i.e. PHP and PHP extensions) allowing you to emulate your production environment, or define your target platform in the Composer project configuration.
After making these changes, run composer update
to get the correct versions of
packages. Be sure to omit the --ignore-version-reqs
flag, because using that
will override these settings.
Couldn't find what you were looking for? We are happy to help you in the forum, on Slack or on Github.