README.md 8.82 KB
Newer Older
1
2
# Mahara Docker

3
This directory contains tools for installing Mahara using Docker.
4
5
6
7

Docker is a great way to try out Mahara without having the hassle of installing
dependencies yourself.

8
The instructions have been tested on Ubuntu 20.04. If you use an older version of Ubuntu, a different flavour of Linux, or use your Docker setup on another operating system, some instructions may not work the same way.
9

10
The commands here assume to be run in a terminal.
11

12
## Set up Docker
13

14
15
16
17
18
19
You can get the most recent version of Docker from the official Docker website
at: https://docs.docker.com/get-docker

Please follow the generic Docker instructions there to make it possible to run without 'sudo'.

Once you have done that, run:
20
21
22
23
```
  docker run ubuntu echo "Yes, I have Docker."
```

24
25
If you have Docker configured, the last line of the output will state:
"Yes, I have Docker."
26

27
28
In order to use the Docker compose files, install Docker compose. You can find
installation instructions at https://docs.docker.com/compose/install
29
30


31
Test that Docker compose is working:
32

33
34
```
docker-compose --version
35
36
```

37
The version output should be greater than 1.28.
38

39
The following scripts and Docker commands can read a lot of config
40
41
variables from the environment.

42
43
44
If there are settings that you always want to make, set them as environment
variables. For example, `export MAHARA_DOCKER_PORT=6142` will set the http
port of the `mahara` Docker container to http://localhost:6142
45
46
47
48

Using a tool such as [Direnv](https://direnv.net/) can make this even easier
because you can define the variables persistently.

49
50
For example, for both local development and running PHPUnit or Behat tests, you
can use an environment variables file to store all necessary config settings
51
52
instead of putting them into config.php itself. You may not wish to do so for a
production environment though when you have multiple Mahara instances running
53
54
55
56
57
58
59
60
61
62
on a single server.

The development setup specified below allows for this approach automatically by using the config specified in `./htdocs/config-environment.php` by default.  

**Note**: Instead of putting values into `config-environment.php`, you can set
up a local .envrc file to contain your custom variables as that will not be
added to the repository when you commit changes, allowing you to keep passwords
more secure, for example. It is excluded in `.gitignore`.

## Work with the Mahara Docker images
63

64
Download the Mahara codebase to use the Docker images. If you work with Git, we recommend you do that via `git clone`:
65

66
67
* From the official Mahara repository: `git clone https://git.mahara.org/mahara/mahara.git`
* From GitHub: `git clone https://github.com/MaharaProject/mahara.git`
68

69
There is no Docker image available on Docker Hub, but you build your own image.
70

71
72
The Mahara Docker image contains the dependencies required for building and
testing Mahara, including generating CSS, PHPUnit and Behat tests.
73

74
### Start up a new development environment
75

76
77
78
79
80
81
In order to allow Docker to have access to and set various Mahara environment variables, a "docker/.env" file is used to set Mahara specific variables.
By default this is copied from `docker/.env-dist` when using `make up` if it does not already exist.

Provide values for two variables:
* MAHARA_URL_SECRET: Set a string as the cron requires it to work correctly.
* MAHARA_PASSWORD_SALT_MAIN: Set a string.
82

83
84
85
If this is your first time running Mahara with Docker, you will need to run
`make docker-image` to build the Mahara Docker image. This will create a Docker
image with Apache, PHP, other dependencies, and of course Mahara.
86
87
88
89
90
91

**Note**: Add Gerrit so you can `make push` later if you want to [contribute your changes](https://wiki.mahara.org/wiki/Developer_Area/Contributing_Code) to the Mahara project.

* Run the command `make up` to start your Mahara Docker environment. This configures your environment automatically.
* Open the URL that you see on screen. It starts with http://localhost:6142/. Mahara is available in a subdirectory, and the name of it is the name of the folder of your repository. If you installed Mahara in the folder 'mahara', then the URL is http://localhost:6142/mahara. If you installed it in the folder '20.10', the URL is http://localhost:6142/20.10.

92
93
Because the code is not part of the Docker image but is available on your computer, the CSS needs to be built outside of Docker. Follow the ['Set up npm and gulp' instructions](https://wiki.mahara.org/index.php/Developer_Area/Developer_Environment) on the Mahara wiki to set that up. Then run `make css` to build the CSS.

94
95
96
97
Useful commands:

* List running containers: `docker ps`
* View logs for a container: `docker logs <container name>`
98
* Run cli commands inside a container: `make docker-bash`
99
100
101

**Note**: Site-specific containers are prefixed with the name of the directory of your site, followed by 'mahara', e.g. 'mahara-mahara' or '20.10-mahara' for repositories in the directories 'mahara' and '20.10' respectively. Shared containers are prefixed 'shared-mahara'.

102
### Shut down the development environment
103
104
105

From the site directory in your terminal, type `make down`. That will shut down all containers unique to this site, i.e. shared containers are not shut down, e.g. if you run multiple Docker images in parallel.

106
107
108
109
110
111
If you type `docker ps` again, you will see the shared containers that are not shut down by `make down`. All shared containers for the Mahara project are prefixed 'shared-mahara'. At the moment, the only two shared containers are `mailhog` and `nginx`. If these are the only two remaining ones, you can shut them down with `make shared-down`.

### Refresh the image

We recommend you refresh your Mahara Docker image periodically (every week or
two) to refresh the image with any security patches from its base image, which includes the operating system: `make docker-image`
112
113
114
115
116
117
118

### Mail setup for development

Mail is delivered to a local mail server called [Mailhog](https://github.com/mailhog/MailHog).

This server is shared between all your development sites.

119
120
**This mail server within Docker will not forward any email to a real mail
server.** Instead, it will keep all mail output and present it at
121
122
123
124
http://localhost:8025

That means that you do not have to configure the config.php variable 'sendallemailto' because mails will not be sent to any address.

125
### Delete a database or sitedata volume for a site
126
127

During development you may wish to delete the database and or sitedata in order to start again from a fresh instance.
128

129
130
131
1. Shut down your site: `make down`.
1. List the volumes: `docker volume ls`. You see a list of volume names, including volumes with the names <Foldername>_mahara-db and <Foldername>_mahara-data.
1. Delete the database volume with `docker volume rm <foldername>_mahara-db` or delete the sitedata volume with `docker volume rm <foldername>_mahara-data`.
132

133
When you run `make up`, new volumes will be created automatically to replace the removed ones providing you with a fresh instance.
134

135
### Database refresh and restore commands
136

137
These commands are for wiping an existing database and restoring a database from a backup file:
138

139
140
* `make docker-database-refresh`: Deletes the current database and creates an empty one.
* `dbpath="/example/database/path.pg" make docker-database-restore`: Restores a database from a database file that you specified in the path. Your previous database will be deleted.
141

142
### Run automated tests
143

144
To run PHPUnit and Behat tests, a different image is required. You can get it by running `make docker-builder`.
145

146
147
**Note**: Running PHPUnit and Behat tests via Docker is in the beginning stages
and not everything may work. We keep the instructions in here though.
148

149
The base command to generate tests (and CSS) is:
150

151
`./docker/make.sh <target>`
152

153
Available `make` commands are:
154

155
156
157
158
159
160
161
* `./docker/make.sh css` to generate css
* `./docker/make.sh phpunit` to run PHPUnit tests
* `./docker/make.sh behat` to run the Behat test suite.
* `./docker/make.sh -e BEHAT_TESTS=change_account_settings.feature behat`
to run only the specified test feature file
* `./docker/make.sh -e BEHAT_MODE=rundebug -e BEHAT_TESTS=change_account_settings.feature behat`
to run only the specified test feature file, watching the browser execute the test.
162

163
164
The Mahara wiki contains more information on [Behat testing](https://wiki.mahara.org/wiki/Testing_Area/Behat_Testing).
  # To run only some test features
165

166
167
The PHPUnit and Behat 'targets' need a database. You can start and stop a test
Docker database with these commands:
168

169
170
171
1. `docker/test-db.sh start` to start a test database
1. Run your tests.
1. `docker/test-db.sh stop` to stop a test database
172

173
To access the database with psql, run `docker/test-db.sh psql`.
174

175
## Mahara Docker in production?
176

177
The Mahara Docker image is **provided for development purposes only** at this stage. If you would like to use it in production, please be aware that you will need to change the Docker compose files and make configuration changes, e.g. passwords, email configuration, caching.