README

Welcome to Summer House

Welcome to Summer House, a fully-dockerized environment for onboarding processes based in Decoupled / Headless Drupal.

• 1. What is Summer House
• 2. Pre-requisites
• 3. Install // Uninstall
• 4. Addresses // Resources
• 5. Troubleshooting
• 6. Useful Links
• 7. Other Projects with similar natura
• 8. Acknowledgments and Thanks

1. What is Summer House

Summer House is a sandbox for Drupal Decoupled projects, generating boilerplate code, built for training purposes and focused on learning-by-doing. The project is self-contained and host environment agnostic. This project deploys a whole Decoupled Drupal platform on-the-fly with a lot of extra-resources, tools and configurations, but only for local development. You can use Summer House for Onboarding processes, workshops and training sessions. Or just for fun.

• See the wiki section for more detailed info: summerhouse/wiki.

2. Pre-requisites

You can use SummerHouse in Linux environments and specifically in Debian / Ubuntu. SummerHouse requires the next resources: Git, Docker, Docker-Compose and DDEV.

If you don't have the prerequisites installed in your host system you can install the resources from a installer script created and committed to the repository. The installer script is here.

Just download the script in your system, give it permissions and execute the installer. This will install Docker, Docker-Compose and DDEV in your Linux system (Ubuntu, Debian). Also it will install some basic resources like git, jq, curl and basic packages.

$ chmod +x installing_docker_dockercompose_ddev.sh
$ ./installing_docker_dockercompose_ddev.sh

Note: If you consider that delegate the prerequisites to a script is insecure or may put your environment at risk, here is some information so you can do it by yourself:

• How to Install Docker
• How To Install Docker Compose
• How to Install DDEV

3. Install // Uninstall

Installating and deploy

You can install Summer House in just three steps, just by doing:

$ git clone https://github.com/davidjguru/summerhouse.git #Get a local copy.
$ cd summerhouse #Move to the folder.
summerhouse$ ddev start #Run the DDEV build up.

And the project will be loaded, configured, enabled and deployed in your local environment. You will see the main URLs opening in your browser.
Please, remember: Summer House is only for local development. It can contain some configs that can be unsecure in other environments.

You can also download the project from the releases / tags area of the Github repository, selecting the version and downloading the compressed folder. Then you only have to unpack the project and launch DDEV:

$ wget https://github.com/davidjguru/summerhouse/archive/refs/tags/v1.0.0.zip
$ unzip summerhouse-1.0.0.zip
$ cd summerhouse-1.0.0/
summerhouse-1.0.0$ ddev start

And the platform will be mounted and deployed.

Uninstalling and clean up

In order to execute a complete cleaning of your Summer House installation you can do the next steps.

$ cd summerhouse
summerhouse$ yes| ddev delete -O #Delete the DDEV register for Summer House.
summerhouse$ ./scripts/utilities/clean_all_docker_related_resources.sh #Will destroy all docker resources.
summerhouse$ cd ..
$ sudo rm -rf summerhouse #Delete all the codebase. 

4. Addresses // Resources

Summer House will deploy a series of containers from an internal network connected by DDEV with external access from your browser:

• Drupal Backend: http://backend.summerhouse.ddev.site
• React Frontend: http://react.summerhouse.ddev.site:3000
• Database: ddev-summerhouse-db:3306 (internal)
• MkDocs: Static Site generator for documents, in http://summerhouse.ddev.site:8091
• PHPMyAdmin: Graphic Interface for the database, in http://summerhouse.ddev.site:8036/
• Portainer: Graphic Interface for managing Containers, in http://summerhouse.ddev.site:9001
• Mailhog: Email testing tool, in http://summerhouse.ddev.site:8025/

5. Troubleshooting

Some common problems have been identified. Check this section for quick interventions.
For more extended information on known bugs and their solutions, visit the related wiki section.

Some ports unavailable

Problems have been detected due to port blocking by other applications. This can cause DDEV start-up problems and lead to others problems during the installation process of the main website, you can get errors just like:

[error]  Drupal\Core\Config\ConfigImporterException: There were errors validating the config synchronization.
Entities exist of type <em class="placeholder">Shortcut link</em> and <em class="placeholder">Shortcut set</em> <em class="placeholder">Default</em>. These entities need to be deleted before importing. in Drupal\Core\Config\ConfigImporter->validate() (line 750 of /var/www/html/backend_drupal/core/lib/Drupal/Core/Config/ConfigImporter.php).

DDEV operates with ports used by other resources, such as 80 or 443. Check that they are not in use (you do not have Apache running on your system).

Error messages accessing external resources

Summer House obtains a lot of resources through the Internet, so sometimes you can get errors when trying to get external resources:

A MkDocs service file has been located in your system.
fatal: unable to access 'https://github.com/davidjguru/summerhouse.wiki.git/': Could not resolve host: github.com
Task failed: Exec command '([ -d ./mkdocs/docs ] && cd ./mkdocs/docs && git pull origin) || (git clone https://github.com/davidjguru/summerhouse.wiki.git ./mkdocs/docs)'

(We're building up the mkdocs container from a git clone of the repository wiki).

This is the key: Could not resolve host: github.com. You need to check in these cases your assigned DNS servers (or those of your ISP), to ensure that they are functioning normally.

Some errors from commands in macOS

When you're installing Summer House in macOS, some people have reported errors in prompt from some commands execution. Specifically, errors derived from some commands used in the installation process not available in macOS, for instance:

bash: xdg-open: command not found

The equivalent command in macOS would be just open, so you can try to change this command in `.ddev/config.yaml', lines 34 to 38.

And:

Task failed: Exec command 'sed -i '12s/restart: "no"/restart: "on-failure"/' ./.ddev/docker-compose.portainer.yaml' on the host: exit status 1

...When we're altering the restarting policies for the Portainer Container by using the sed command.

Remember, more information on how to deal with more specific errors can be found here:
summerhouse/wiki/troubleshooting.

6. Useful Links

• See the Issue Queue: summerhouse/issues
• See the Work In Progress: summerhouse/project
• See the related Milestones: summerhouse/milestones
• See the Documentation pages: summerhouse/wiki

7. Other projects with similar natura

Summer House may not be exactly what you're looking for, but it comes close. If you want to check out other projects that might be closer to your needs, you can try the cases in the following list:

• Decoupled Drupal 8 with GatsbyJS Frontend built over Docksal
• Metadrop's Drupal Boilerplate built over Docker4Drupal
• Systemseed's Drupal ReactJS Boilerplate, built over Docker4Drupal

8. Acknowledgments and Thanks

• Thanks to Digitalist Sweden for the opportunity to improve the onboarding processes.
• Thanks to Helena Nordenfelt for giving me the chance to focusing on this idea.
• Thanks to Randy Fay for the amazing work in DDEV and its community.
• Thanks to Pedro Cambra from Cambrico, for being a true mentor.