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:
- all-in Docker (easiest)
- selective Docker (recommended because it’s more flexible and has better performance while being only slightly harder to set up)
- don’t use Docker at all (hardest).
1. All-in Docker
To run Ginger completely in Docker containers, open a terminal and enter:
$ make upTo open a Zotonic shell:
$ make shellTo run Gulp in the Ginger directory:
$ make gulp site=your_site_nameTo run the tests for a module, e.g. mod_ginger_collection:
$ docker-compose run zotonic bin/zotonic runtests mod_ginger_collectionIf you want to run tests repeatedly, it may be easier to open a shell in a clean Zotonic container:
$ make promptand 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 --forceThen 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.configPoint Zotonic to your Ginger sites/ and modules/ directories:
$ mkdir zotonic/user
$ ln -s ../../ginger/sites zotonic/user/sites
$ ln -s ../../ginger/modules zotonic/user/modulesAnd run Zotonic:
$ cd ginger
$ make startSee 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/hostsfile.
Checking out sites
- Check out your Zotonic site in the
sites/directory. - Start the site from the status site: http://localhost.
- Login and go to the modules page
- Deactivate site module and activate it again
- 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):
- Fetch changes:
$ git fetch. - View branches:
$ git branch -a. - Switch to the latest release branch:
$ git checkout release-0.1.0. - Make, commit and push your changes.
- 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().- 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:
- Fetch changes:
$ git fetch. - Switch to master:
$ git checkout master. - 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 pullThen 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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent