Ginger

This is the Ginger Zotonic edition. This repository contains:

• (most) Ginger modules
• Docker configuration
• shell scripts

Documentation

• Docker development environment
• Guidelines
• Why Ginger is a single Git repository
• Releases
• Browser tests
• Templates
• Anymeta import
• Troubleshooting

Getting started

Clone this repository and install Docker.

You can run Ginger in three ways:

1. all-in Docker (easiest)
2. selective Docker (recommended because it’s more flexible and has better performance while being only slightly harder to set up)
3. don’t use Docker at all (hardest).

1. All-in Docker

To run Ginger completely in Docker containers, open a terminal and enter:

$ make up

To open a Zotonic shell:

$ make shell

To run Gulp in the Ginger directory:

$ make gulp site=your_site_name

To run the tests for a module, e.g. mod_ginger_collection:

$ docker-compose run zotonic bin/zotonic runtests mod_ginger_collection

If you want to run tests repeatedly, it may be easier to open a shell in a clean Zotonic container:

$ make prompt

and then make and run the tests:

$ make && bin/zotonic runtests mod_ginger_collection

For more, see the Docker doc chapter.

2. Selective Docker (recommended)

Due to limitations in Docker for Mac, file synchronization performance suffers when you have large amounts of files (i.e. many sites with node_modules/ directories).

By running Zotonic directly on your host (outside Docker) we circumvent this limitation. Another advantage is that you can directly make changes in Zotonic source code, too.

All other services (PostgreSQL, Elasticsearch, Kibana) still run in containers.

First, install Zotonic’s dependencies, including Erlang:

$ brew install erlang@21 fswatch imagemagick
$ brew link erlang@21 --force

Then clone both Ginger and Zotonic:

$ git clone https://github.com/driebit/ginger.git
$ git clone https://github.com/zotonic/zotonic.git --branch 0.x 

Copy Ginger’s configuration file, which includes its dependencies:

$ mkdir -p ~/.zotonic/0
$ cp ginger/config/zotonic.config ~/.zotonic/0/zotonic.config

Point Zotonic to your Ginger sites/ and modules/ directories:

$ mkdir zotonic/user
$ ln -s ../../ginger/sites zotonic/user/sites
$ ln -s ../../ginger/modules zotonic/user/modules

And run Zotonic:

$ cd ginger
$ make start

See Troubleshooting if you get errors.

You have to enter your account’s sudo password to enable port forwarding (from port 80 to 8000).

First the supporting Docker containers are started, then Zotonic is run. Zotonic is then available on http://localhost.

When you quit Zotonic, the Docker containers are stopped as well.

Sites overview

• The Zotonic status site is available at http://localhost. Log in with empty password.
• Make sure to add the hostnames of individual sites (e.g. yoursite.docker.test) to your /etc/hosts file.

Checking out sites

1. Check out your Zotonic site in the sites/ directory.
2. Start the site from the status site: http://localhost.
3. Login and go to the modules page
4. Deactivate site module and activate it again
5. Now the site should work properly

Adding modules

Place custom modules in modules/ (no symlinks needed).

Fetching changes

$ git fetch
$ git rebase

Making changes

Commit messages

Please follow the Driebit guidelines for commit messages. Additionally, prefix your message with the module that your change applies to. For instance:

[admin] Fix login form styling
[foundation] Add carousel template

Bugfixes to the release branch

When you are fixing a bug in the current release branch (as it is published on ginger-test or ginger-acceptatie):

1. Fetch changes: $ git fetch.
2. View branches: $ git branch -a.
3. Switch to the latest release branch: $ git checkout release-0.1.0.
4. Make, commit and push your changes.
5. Optionally, update ginger-test with the your changes to the release branch:

$ ssh ginger-test.driebit.net
$ cd /srv/zotonic/
$ z git pull
$ z zotonic shell
$ z:m().

6. Optionally, the release branch to master:

git checkout master
git pull
git merge release-0.#.0 (latest release branch)
git push

Feature developments

When working on (larger) features and fixes that should not be part of the current release:

1. Fetch changes: $ git fetch.
2. Switch to master: $ git checkout master.
3. Make, commit and push your changes.

Deploying sites

To deploy a site, log in to the proper server (ginger-test.driebit.net, ginger-acceptatie.driebit.net or ginger01.driebit.net):

$ ssh ginger-test.driebit.net
$ cd /srv/zotonic/sites/[site name]

Check the current Git branch, then pull the latest changes:

$ z git pull

Then compile the changes and flush the site:

$ z zotonic shell
$ z:compile(), z:flush([site name]).

License

Ginger is released under the Apache 2.0 License. See the included LICENSE file for more information.