Skip to content

Commit

Permalink
docs: update docs references for pygmystack and lagoon
Browse files Browse the repository at this point in the history
  • Loading branch information
tobybellwood committed Apr 12, 2024
1 parent 46238cf commit ebc9dcc
Show file tree
Hide file tree
Showing 10 changed files with 48 additions and 23 deletions.
13 changes: 5 additions & 8 deletions docs/drupal_site_containers.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,14 @@ During [Part I](./local_docker_development.md#part-i-shared-docker-containers) w

## Find the right `docker-compose.yml`

1. Visit https://github.com/amazeeio/docker or clone https://github.com/amazeeio/docker.git into a folder on your computer
1. Visit https://github.com/uselagoon/lagoon-examples or clone https://github.com/lagoon-examples/drupal9-base.git into a folder on your computer
2. Copy the desired example file into your Drupal directory (see descriptions below). Use `example-docker-compose-drupal.yml` if unsure.
3. Rename the file to `docker-compose.yml`
4. Edit the file according to your needs, change at least the host name. _BTW: It's perfectly fine to commit this file into your git repository, so others that are also using amazee.io docker can use it as well._
4. Edit the file according to your needs, change at least the host name. _BTW: It's perfectly fine to commit this file into your git repository, so others that are also using docker can use it as well._
5. Run in the same directory as the `docker-compose.yml`:

docker-compose up -d
6. If you are on Windows add the URL to the Hosts file (see [windows documentation](local_docker_development/windows.md) for that).
6. If you are on Windows add the URL to the Hosts file (see [windows documentation](local_docker_development.md) for that).
7. Open your browser with the entered URL in the `docker-compose.yml`, happy Drupaling!

## Connect to the container
Expand Down Expand Up @@ -78,7 +78,7 @@ When you next start a bash session, you'll be able to use `ddrush` just like you

## Update Images

We constantly make improvements, updates and some other nice things to our container images. Visit [changelog.amazee.io](https://changelog.amazee.io) to see if there is something new. If you need to update the Docker Images to the newest version from the Docker Hub run in the same folder as the `docker-compose.yml`:
We constantly make improvements, updates and some other nice things to our container images. Visit the [Lagoon Image releases page](https://github.com/uselagoon/lagoon-images/releases) to see if there is something new. If you need to update the Docker Images to the newest version from the Docker Hub run in the same folder as the `docker-compose.yml`:

docker-compose pull
docker-compose up -d
Expand All @@ -92,7 +92,4 @@ Just open another terminal window at the exact same directory than you run the f

## `docker-compose.yml` example files

| Example File | PHP | Services | Description |
|----------------------------------------------------------------------------------------------------------------------------------|--------|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`example-docker-compose-drupal.yml`](https://github.com/amazeeio/docker/blob/master/example-docker-compose-drupal.yml) | 5.6/7.0/7.1| nginx, varnish, mariadb |Drupal container without provisions for solr. See comments in file for choosing PHP version and customizing for Composer sites |
| [`example-docker-compose-drupal-solr.yml`](https://github.com/amazeeio/docker/blob/master/example-docker-compose-drupal-solr.yml)| 5.6/7.0/7.1| nginx, varnish, mariadb, solr |Drupal container with provisions for solr. See comments in file for choosing PHP version and customizing for Composer sites |
Visit https://github.com/uselagoon/lagoon-examples to see a range of example projects that you can clone as a starting point
Binary file added docs/images/pygmystack_icon.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/pygmystack_icon_wh.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/pygmystack_taglone_col.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
27 changes: 24 additions & 3 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,31 @@
# Pygmy
# Welcome to pygmystack

`pygmy` is the single tool needed to get the local [amazee.io](https://amazee.io) Docker Drupal Development Environment running on your Linux based system. It built to work with [Docker for Mac](https://docs.docker.com/docker-for-mac/)! (quite a lot for such a [small whale](https://en.wikipedia.org/wiki/Pygmy_sperm_whale) 🐳)
The pygmy stack is a container stack for local development.

It is a collaboration between:

* [amazee.io](https://www.amazee.io) - Initial development of pygmy, and it's predecessor, [cachalot](https://github.com/amazeeio/cachalot)
* [@fubarhouse](https://github.com/fubarhouse) - complete rewrite of pygmy in Golang (Thanks Karl!)
* [the Lagoon team](https://lagoon.sh) - ongoing support and maintenance

Please see [github.com/pygmystack](https://github.com/pygmystack) for more information

**Why use `pygmy`?**

* Starting the necessary Docker Containers for your Docker Development Environment
The pygmy stack is a container stack for local development, and `pygmy` is the main tool.

It's built to work with:

- [Docker Desktop for Mac](https://docs.docker.com/desktop/mac/)
- [Docker Desktop for Windows](https://docs.docker.com/desktop/windows/)
- [Docker Engine for Linux](https://docs.docker.com/engine/)

Quite a lot for such a [small whale](https://en.wikipedia.org/wiki/Pygmy_sperm_whale) 🐳)

**What `pygmy` will handle for you:**

* Starting the necessary Docker Containers for the amazee.io Drupal Docker Development
* Starting the necessary Docker Containers for local development
* If on Linux: Adds `nameserver 127.0.0.1` to your `/etc/resolv.conf` file, so that your local Linux can resolve `*.docker.amazee.io` via the dnsmasq container
* If on Mac with Docker for Mac: Creates the file `/etc/resolver/docker.amazee.io` which tells OS X to forward DNS requests for `*.docker.amazee.io` to the dnsmasq container
* Tries to add the ssh key in `~/.ssh/id_rsa` to the ssh-agent container (no worries if that is the wrong key, you can add more any time)
Expand Down
10 changes: 10 additions & 0 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,16 @@ Make sure you have the following dependencies installed:

## Installation

### Installing from homebrew (recommended for most users)

**Works for**: Linux & MacOS

```shell
brew tap pygmystack/pygmy;
brew install pygmy;
```


### Installing from a precompiled binary

Releases on GitHub accompany binaries [available for download](https://github.com/pygmystack/pygmy/releases).
Expand Down
12 changes: 6 additions & 6 deletions docs/local_docker_development.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@

# Local Drupal Docker Development

amazee.io supports development workflows which involve local development sites. We provide a Drupal Docker development environment that runs on your local computer.
It uses the exact same configuration for **all** services like on the amazee.io servers. This means:
Lagoon supports development workflows which involve local development sites. We provide a Drupal Docker development environment that runs on your local computer.
It uses the exact same configuration for **all** services like on the Lagoon servers. This means:

* If the site runs locally, it also runs on production
* You can use the exact same `settings.php` file for local and production

**And the best:** You don't need to have any amazee.io account or site running in order to use the local development environment! Just install it, and experience all the benefits of amazee.io for free.
**And the best:** You don't need to have a Lagoon account or site running in order to use the local development environment! Just install it, and experience all the benefits of Lagoon for free.

The Docker based Drupal Development environment consists of two parts:

Expand All @@ -23,7 +23,7 @@ The Docker Containers which will run Drupal. These are made to be copied into a

## What it includes

The amazee.io Local Docker Drupal Development environment equips you with all the tools you need to develop your Drupal site locally:
An example local Docker Drupal Development environment, such as https://www.github.com/lagoon-examples/drupal9-solr, equips you with all the tools you need to develop your Drupal site locally:

* **Webserver:** Nginx
* **Frontend Caching:** Varnish
Expand All @@ -34,7 +34,7 @@ The amazee.io Local Docker Drupal Development environment equips you with all th
* **Dependency Manager for PHP:** Composer
* NodeJS / NPM

For more information about software components used in the amazee.io Stack head over to the [Components](../architecture/components.md) overview page.
For more information about software components used in the Lagoon Stack head over to [their docs](https://docs.lagoon.sh).

## How this works

Expand All @@ -50,7 +50,7 @@ It is possible to add mount ssh private keys into Docker containers, but this is

### The Solution

amazee.io implemented a Drupal Docker Development environment which handles all these issues nicely for you. It allows you to:
`pygmy` allows you to:

* Access all sites via the Port 80 or 443 with just different URLs like site1.docker.amazee.io and site2.docker.amazee.io
* Add your SSH Key once to the system and can forget about it, no need to add it to each container
Expand Down
2 changes: 1 addition & 1 deletion docs/map_addtitional_ports.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ If you need to map other ports, simply add them to the `ports` section and resta

### Example for Solr

If you use one of amazee.io Drupal containers with Solr included, your Solr URL most likely looks like this: http://127.0.0.1:8149/solr/drupal/
If you use one of Lagoon's Drupal containers with Solr included, your Solr URL most likely looks like this: http://127.0.0.1:8149/solr/drupal/

In this case, to play with Solr queries:
- add `"8149"` to the `ports` section of `docker-compose.yml` file
Expand Down
6 changes: 2 additions & 4 deletions docs/ssh_agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@

Per default your SSH Key at `~/.ssh/id_rsa` is added to the Docker containers from `pygmy`

If you need another key, read the documentation of [`pygmy`](linux_pygmy.md) about this.

## How it works
1. `pygmy` starts `amazeeio/ssh-agent` container with a volume `/tmp/amazeeio_ssh-agent`
2. `pygmy` adds a default SSH key from the host into this volume
Expand All @@ -13,14 +11,14 @@ If you need another key, read the documentation of [`pygmy`](linux_pygmy.md) abo
- container:amazeeio-ssh-agent
```
4. When CLI container starts, the volume is mounted and an entrypoint script adds SHH key into agent.
@see https://github.com/amazeeio/lagoon/blob/master/images/php/cli/10-ssh-agent.sh
@see https://github.com/uselagoon/lagoon-images/blob/main/images/php-cli/entrypoints/10-ssh-agent.sh

Running `ssh-add -L` within CLI container should show that the SSH key is correctly loaded.

## Troubleshooting
### SSH Key issues

As everything on amazee.io works with key authentication sometimes you might run into issues where the drush aliases aren't displayed or you can't connect to the servers.
As everything on Lagoon works with key authentication sometimes you might run into issues where the drush aliases aren't displayed or you can't connect to the servers.

Could not load API JWT Token, error was: 'lagoon@ssh.lagoon.amazeeio.cloud: Permission denied (publickey).'

Expand Down
1 change: 0 additions & 1 deletion docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,6 @@ To find such issues, we need to analyze the docker logs, do that via:
amazee_io.docker.amazee.io | Child (246) said Child starts

Check the latest few lines of code and you probably see the issue.
Stuck here? Join our Slack at [slack.amazee.io](https://slack.amazee.io) and we help you.

### Shared container logs

Expand Down

0 comments on commit ebc9dcc

Please sign in to comment.