Docksal Pantheon Setup from Scratch

I recently had reason to switch over to using Docksal for a project, and on the whole I really like it as a good easy solution for getting a project specific Drupal dev environment up and running quickly. But like many dev tools the docs I found didn’t quite cover what I wanted because they made a bunch of assumptions.

Most assumed either I was starting a generic project or that I was starting a Pantheon specific project – and that I already had Docksal experience. In my case I was looking for a quick emergency replacement environment for a long-running Pantheon project.

Fairly recently Docksal added support for a project init command that helps setup for Acquia, Pantheon, and, but pull init isn’t really well documented and requires a few preconditions.

Since I had to run a dozen Google searches, and ask several friends for help, to make it work I figured I’d write it up.

Install Docksal

First follow the basic Docksal installation instructions for your host operating system. Once that completes, if you are using Linux as the host OS log out and log back in (it just added your user to a group and you need that access to start up docker).

Add Pantheon Machine Token

Next you need to have a Pantheon machine token so that terminus can run within the new container you’re about to create. If you don’t have one already follow Pantheon’s instructions to create one and save if someplace safe (like your password manager).

Once you have a machine token you need to tell Docksal about it.  There are instructions for that (but they aren’t in the instructions for setting up Docksal with pull init) basically you add the key to your docksal.env file:


 Also if you are using Linux you should note that those instructions linked above say the file goes in $HOME/docksal/docksal.env, but you really want $HOME/.docksal/docksal.env (note the dot in front of docksal to hide the directory).

Setup SSH Key

With the machine token in place you are almost ready to run the setup command, just one more precondition.  If you haven’t been using Docker or Docksal they don’t know about your SSH key yet, and pull init assumes it’s around.  So you need to tell Docksal to load it but running:
fin ssh-key add  

If the whole setup is new, you may also need to create your key and add it to Pantheon.  Once you have done that, if you are using a default SSH key name and location it should pick it up automatically (I have not tried this yet on Windows so mileage there may vary – if you know the answer please leave me a comment). It also is a good idea to make sure the key itself is working right but getting the git clone command from your Pantheon dashboard and trying a manual clone on the command line (delete once it’s done, this is just to prove you can get through).

Run Pull Init

Now finally you are ready to run fin pull init: 

fin pull init --hostingplatform=pantheon --hostingsite=[site-machine-name] --hosting-env=[environment-name]

Docksal will now setup the site, maybe ask you a couple questions, and clone the repo. It will leave a couple things out you may need: database setup, and .htaccess.

Add .htaccess as needed

Pantheon uses nginx.  Docksal’s formula uses Apache. If you don’t keep a .htaccess file in your project (and while there is not reason not to, some Pantheon setups don’t keep anything extra stuff around) you need to put it back. If you don’t have a copy handy, copy and paste the content from the Drupal project repo:

Finally, you need to tell Drupal where to find the Docksal copy of the database. For that you need a settings.local.php file. Your project likely has a default version of this, which may contain things you may or may not want so adjust as needed. Docksal creates a default database (named default) and provides a user named…“user”, which has a password of “user”.  The host’s name is ‘db’. So into your settings.local.php file you need to include database settings at the very least:

$databases = array(
  'default' =>
      'default' =>
        'database' => 'default',
        'username' => 'user',
        'password' => 'user',
        'host' => 'db',
        'port' => '',
        'driver' => 'mysql',
        'prefix' => '',

With the database now fully linked up to Drupal, you can now ask Docksal to pull down a copy of the database and a copy of the site files:

fin pull db

fin pull files

In the future you can also pull down code changes:

fin pull code

Bonus points: do this on a server.

On occasion it’s useful to have all this setup on a remote server not just a local machine. There are a few more steps to go to do that safely.

First you may want to enable Basic HTTP Auth just to keep away from the prying eyes of Googlebot and friends.  There are directions for that step (you’ll want the Apache instructions). Next you need to make sure that Docksal is actually listing to the host’s requests and that they are forwarded into the containers.  Lots of blog posts say DOCKSAL_VHOST_PROXY_IP= fin reset proxy. But it turns out that fin reset proxy has been removed, instead you want: 

DOCKSAL_VHOST_PROXY_IP= fin system reset.  

Next you need to add the vhost to the docksal.env file we were working with earlier:


Run fin up to get Docksal to pick up the changes (this section is based on these old instructions).

Now you need to add either a DNS entry someplace, or update your machine’s /etc/hosts file to look in the right place (the public IP address of the host machine).

Anything I missed?

If you think I missed anything feel free to let know. Particularly Windows users feel free to let me know changes related to doing things there. I’ll try to work those in if I don’t get to figuring that out on my own in the near future.

6 thoughts on “Docksal Pantheon Setup from Scratch”

  1. This could be the answer to the issues we are having with Pantheon. What makes this interesting is that it *appears* to provide the ability to run a pre-designed Drupal instance that does not necessarily fit the file organizational structure mandated by Pantheon.

    Unfortunately, the example seemed to clone an instance layed out by Pantheon – then running that locally.

    I don’t see the value in that.

    What would be of value is to take a site developed locally and be able to run it on Pantheon without dealing with their ridged file/folder layout mandates

    1. Many developers find having a local copy of a web site they can modify, test, and debug useful. But nothing about this blog post was meant to change their file system patterns.

      The folder structures have allowed them to add security to their platform that radically changes the attack surface vs more traditional ways of hosting, and I’ve seen places where that has done things like limited the impact of password breaches to prevent escalation attacks that widen the scale of the breach wildly. But it does force you into a very small number of patterns (two if we’re counting): Nested Doc Root, Doc root in project root (

      In Pantheon’s default projects, nested docroot is disabled, and you see all of Drupal core in the project root, and you have to follow their instructions to put things you don’t want web readable into a specific directory or not in the project at all. I personally dislike that this is their default, but it is, and such is life. Most importantly, if you want to use the one click updates from the dashboard you much use this mode (see link above).

      When nested docroot is enabled, you see all Drupal related files moved into a directory called web, and you can place config, vendor, and other things outside the web root. I think this mode is far better, and my experience is that most complex projects use this mode, in combination with a number of other tooling changes, to keep things well organized (it is not more secure).

      Pantheon, for better or worse, uses an approach that requires developers to embrace their constraints. You can love them or hate them, but the platform constraints are there and many are essentially immutable. If you cannot learn to work well within them you will always struggle on their setup. Once you embrace them, you stop noticing some (I rarely think about the file system setup anymore), and learn to use the others at an interesting challenge or project limit (see my post of running forever on the platform — that was fun to figure out).

  2. Why isn’t there a fin push…
    Makes no sense to be able to “FIN PULL” But never be able to get the code back up to Pantheon

    What am I missing?

    1. I didn’t really mean to leave out mention of code push, but in the environment I was working in pushing directly to Pantheon wasn’t part of the process because there was a CI setup involved. That makes the actual loop was much longer: code and config pushes go to github, then CircleCI builds and pushes to Pantheon’s repos, which deploys the code and executes a final set of script to handle config changes.

      fin pull is designed to help support some common hosting providers and pull down projects quickly to get your local setup for a developer who already has 3 or 4 other projects running. It kinda assume you know so extra things (several of those assumptions lead to this post cause they weren’t true for me, like the missing ssh key reference) including how the workflow on that platform works in general.

      If you are using Pantheon’s repo as project repo, you should be able to commit and push code using standard git commands (this is the generic workflow on their platform using a monolithic repo):

      git add .
      git commit -m “I made a change, and described it here well”
      git push

      After that, the details are up to your project team. If you use a CI, that would require some adjustment, when using composer (and you should be on Drupal 8 projects) you might want to tweak the .gitignore to change what’s being provided, you way adjust the pantheon.yml file and change how that impacts the system, etc.

  3. Just wanted to say, THANK YOU, this was an extremely helpful post. I spent days on this, this week, and this was a huge help.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.