Step-by-step instructions (last updated October 2024).
Navigate to your project directory and start your new codebase there:
cd ~/Projects
composer create-project drupal/recommended-project:^10 standard_acsf
cd standard_acsf
Change "web" to "docroot" (because that is what we use on Acquia). This command will backup the original file before modifying it:
sed -i'.original' 's/web\//docroot\//g' composer.json
Remove the /web directory, then use composer to reinstall it at /docroot:
rm -rf web
rm composer.lock
composer install
Add a .gitignore file. Simply clone the example.gitignore file included with Drupal core, but then use your preferred code editor to uncomment line 12 and lines 38-39 so that the Drupal /core directory and generated files will be omitted from the source code repo. The best practice is to avoid including the vendor directory in your source code because it changes often and it's not really part of the project (it's just a dependency). We can also avoid committing Drupal core itself (as it will rebuild itself with composer) and avoid user-generated content to the repo (proper separation of code and content).
cp docroot/example.gitignore .gitignore
Add Drush, and the Site Factory Connector module. (Although Drush 13 exists, I prefer to avoid the bleeding edge and use the prior stable version.)
composer require drush/drush:^12
composer require drupal/acsf
Create a custom installation profile that we can use to create new sites on Site Factory. To keep things simple, we will clone the standard profile included with Drupal core. We will name our custom profile standard_acsf and we will add it to /docroot/profiles/custom directory:
mkdir docroot/profiles/custom
cp -rvp docroot/core/profiles/standard docroot/profiles/custom/standard_acsf
Back up the original files before editing anything:
cp standard.info.yml standard.info.yml.original
cp standard.install standard.install.original
cp standard.install standard.links.menu.yml.original
cp standard.profile standard.profile.original
Rename the files for our new custom profile:
mv standard.info.yml standard_acsf.info.yml
mv standard.install standard_acsf.install
mv standard.links.menu.yml standard_acsf.links.menu.yml
mv standard.profile standard_acsf.profile
Now you're ready to edit the standard_acsf.info.yml file. Use vim or your preferred text editor. Simply delete the first 5 lines, and replace them with lines below:
name: Standard ACSF
type: profile
description: 'Install with commonly used features pre-configured. (Modified slightly for ACSF.)'
core_version_requirement: '^8.8 || ^9 || ^10'
install:
- acsf
- acsf_duplication
- acsf_theme
- acsf_variables
Now you're ready to test your custom installation profile using DDEV. If you haven't installed DDEV, use the commands below to install it — this assumes macOS. If you already have DDEV, you can skip ahead.
brew install --cask orbstack
brew install ddev/ddev/ddev
brew install mkcert (or brew reinstall mkcert)
mkcert -install
Configure DDEV (the defaults should be fine) and start the container:
ddev config
ddev start
You may want to pause here and edit your DDEV configuration to use PHP 8.2, not 8.3. (As with Drush, I don't like to be on the bleeding edge of PHP.)
vim .ddev/config.yaml
Now restart DDEV and test your installation.
ddev restart
ddev ssh
drush site:install standard_acsf -y
drush uli
exit
Please note: There is no point in continuing this tutorial until the site:install is working. (The 2 screenshots below indicate a successful install within DDEV.)
Create a free public git repo at github.com. (Mine is https://github.com/markf3lton/standard-acsf.) Run these commands to save your work-in-progress.
git init
git add -A
git commit -m "Initial commit with a custom profile: standard_acsf."
git status
git remote add origin [email protected]:markf3lton/standard-acsf.git (use your repo)
git branch -M main
git push --set-upstream origin main
We cannot run Drupal on Site Factory until some necessary include files have been added.
drush acsf-init-verify --root=docroot/modules/contrib/acsf/acsf_init --include=docroot/modules/contrib/acsf/acsf_init
drush acsf-init --root=docroot/modules/contrib/acsf/acsf_init --include=docroot/modules/contrib/acsf/acsf_init
To prevent the Drupal's core composer scaffold from overwriting your .htaccess file, add an exclusion to your composer.json file. Specifically, edit the "extra" section to include the "file-mapping" section, as indicated below:
"extra": {
"drupal-scaffold": {
"locations": {
"web-root": "docroot/"
},
"file-mapping": {
"[web-root]/.htaccess": false,
"[web-root]/sites/development.services.yml": false
}
},
Commit these changes to the repo.
git status
git add -A
git commit -m "Run acsf-init to include required files."
git push
At this point, you should have a codebase that will run on Site Factory!
(I will assume you already have Acquia CLI installed.) You may name your branch whatever you like, but the convention is to append -build to your branch name, so it is clear the branch contains a production-ready build artifact.
acli push:artifact --destination-git-branch=standard-acsf-build
Now you need to test your code on Site Factory.
First, log into your Site Factory Management Console (SFMC) for 01test and confirm you can deploy the build branch via https://www.[your-management-console].acsitefactory.com/admin/gardens/site-update/update.
Second, enable your custom installation profile. Visit https://www.[your-management-console].acsitefactory.com/preferences/site-factory-management/sf-profile-management and modify the configuration, as pictured below.
Enable custom installation profile for Site Factory
Finally, confirm that you can create a brand new site following the guide at https://docs.acquia.com/site-factory/manage/website/groups-create#section-creating-new-websites