Pick a directory where you will store all your (Docksal) projects.
On Mac and Linux, the recommended “Projects” directory is ~/Projects.
On Mac, the directory must be within /Users. There are no restrictions for Linux.
On Windows, the recommended “Projects” directory is C:\Projects.
The directory must be within the Windows (and not WSL) filesystem (i.e., you cannot use ~/Projects in WSL on Windows).
Whether you have an existing codebase or want to start from scratch, you can initialize a dedicated basic LAMP stack for a project/directory with a single command:
fin init
Run the command within your “Projects” directory and follow onscreen instructions.
$ mkdir -p ~/Projects/myproject
$ cd ~/Projects/myproject
$ fin init
Initialize a project in /Users/leonid/Work/Projects/myproject? [y/n]: y
DOCROOT has been detected as docroot. Is that correct? [y/n]: y
Configuration was generated. You can start it with fin project start
Starting services...
Creating network "myproject_default" with the default driver
Creating volume "myproject_cli_home" with default driver
Creating volume "myproject_project_root" with local driver
Creating volume "myproject_db_data" with default driver
Creating myproject_db_1 ... done
Creating myproject_cli_1 ... done
Creating myproject_web_1 ... done
Connected vhost-proxy to "myproject_default" network.
Waiting for project stack to become ready...
Project URL: http://myproject.docksal
Open http://myproject.docksal in your browser to verify the setup.
The directory name becomes the project name as well as the virtual host name.
Only lowercase alphanumeric, underscore, and hyphen are allowed in the project/directory name.
If your project does not use a sub-directory for the document root, then use . as the DOCROOT when asked by the wizard.
If you see requests for the SSH key passphrase for id_dsa or id_rsa, those are the keys in your ~/.ssh folder.
SSH keys are automatically loaded into the ssh-agent container and can then be used by any Docksal project stack
running on your machine. Read more about the ssh-agent system service in Docksal.
Running fin init again will reset your project stack. See fin help project for the list of project level commands.
MySQL connection settings are injected via environment variables. You can access those via getenv() in PHP.
<?php
$host = getenv('MYSQL_HOST');
$user = getenv('MYSQL_USER');
$pass = getenv('MYSQL_PASSWORD');
$db = getenv('MYSQL_DATABASE');
echo "mysql://$user:$pass@$host/$db";
You can start from a boilerplate repo using the wizard:
fin project create
Run the command within your “Projects” directory and follow onscreen instructions.
$ fin project create
1. Name your project (lowercase alphanumeric, underscore, and hyphen): demo
2. What would you like to install?
PHP based
1. Drupal 10 (Composer Version)
2. Drupal 10 (BLT Version)
3. Drupal 9 (Composer Version)
4. Drupal 9 (BLT Version)
5. Drupal 7
6. Wordpress
7. Magento
8. Laravel
9. Symfony Skeleton
10. Symfony WebApp
11. Grav CMS
12. Backdrop CMS
Go based
13. Hugo
JS based
14. Gatsby JS
15. Angular
HTML
16. Static HTML site
Custom
0. Custom git repository
...
Enter your choice (0-16): 1
Project folder: /Users/username/Projects/demo
Project software: Drupal 8
Source repo: https://github.com/docksal/boilerplate-drupal8.git
Project URL: http://demo.docksal
Do you wish to proceed? [y/n]: y
Cloning repository...
...
3. Passing execution to fin init...
...
Open http://demo.docksal in your browser to verify the setup.
DONE! Completed all initialization steps.
Open http://demo.docksal in your browser to verify the setup.
Site provisioning can be automated via a custom command.
Every Docksal powered project has at least one custom command - fin init (stored in .docksal/commands/init).
The init command should facilitate project provisioning from zero to a fully working application.
It should be used to automate project specific initialization tasks, like:
It is recommended to break different steps into a dedicated custom command, then invoke
them in the init command.
For a working example of a Docksal powered project with fin init take a look at:
These are the repos used by the fin project create wizard.