Using Docker it's possible to fire up Emoncms on a bare system (assuming Docker is installed) in a couple of minutes with all the LAMP install & config taken care of.
This is great for development since it's possible to play about with Emoncms running in a Docker container without fear of messing up your main Emoncms install.
In the future, Docker can even be used as a deployment tool for Emoncms. In theory, it should be possible to deploy the Docker container on any server within minutes :-)
We have taken a multi-container approach with php-apache running in one container and the MYSQL database running in another. The containers are linked using docker-compose.
If running Linux Docker-compose will also need to be installed separately. Docker-toolbox on Mac and Windows includes Docker-compose
If running on Linux highly recomended to create Docker group to avoid having to use
sudo with Docker commands:
$ sudo groupadd docker $ sudo usermod -aG docker <YOUR-USER-NAME> $ docker run hello-world
After restarting terminal (logout & logback in), you should now be able to
docker run hello-world without
Pull openenergymonitor/emoncms:latest from docker hub and use Docker-compose to link the emoncms container (PHP & Apache) to the MYSQL container.
$ git clone https://github.com/emoncms/emoncms-docker $ cd emoncms-docker $ docker pull openenergymonitor/emoncms:latest $ docker-compose up
That's it! Emoncms should now be running in Docker container, browse to http://localhost:8080
Setup dev enviroment
If you want to edit the emoncms file (dev) it's best to clone them externally to docker then mount volume into the container:
volumes: ##mount emoncms files from local FS for dev - ./emoncms:/var/www/html
Then clone the repos into
$ ./bin/setup_dev_repositories $ docker-compose pull $ docker-compose up
If you get an error
bind: address already in use, this means there is already a process on the host machine listening on port 8080. You can check what processes are listening on ports by running
sudo netstat -plnt. There are two options, either change the emoncms web container port to use a different port then rebuild the container or kill the process currently running on the host machine using the same port.
Build Emoncms Docker Containers
Note: If Emoncms Docker being used for production / testing (i.e modifing the Emoncms files at run-time is not required) there is no need to clone emoncms core & modules since by default the Emoncms git master branch is cloned when the containers are built (see Dockerfile), this cloned 'snapshot' is then overwritten by the Emoncms files mounted from local file-system when running development docker-compose (default)
Run the following script to clone the
emoncms repository along with the
Further modules can be found in the emoncms git repo e.g. backup, wifi etc.
The file structure should look like:
+-- emoncms-docker ¦ +-- Dockerfile ¦ +-- docker-compose.yml +-- emoncms ¦ +-- <emoncms-core files> ¦ +-- e.g index.php ¦ +-- Modules ¦ +-- <core-modules> e.g. admin, feed, input ¦ +-- <optional-modules> e.g dashboard
MYSQL Database Credentials
For development the default settings in
default.docker.env are used. For production a
.env file should be created with secure database Credentials. See Production setup info below.
config/php.ini to add custom php settings e.g. timezone (default Europe)
Build / update Docker container
Required on first run or if
Docker-compose.yml are changed:
$ docker-compose build
Start Emoncms containers
Start as foreground service:
$ docker-compose up
Stop with [CTRL + c]
That's it! Emoncms should now be runnning in Docker container, browse to http://localhost:8080
Start as background service:
$ docker-compose up -d
Docker compose up will start two containers:
emon_webwhich is based on the official Docker PHP-Apache image
emon_dbwhich is based on the offical Docker MYSQL image
How Docker Compose works...
Infomation about how docker-copose workin in Emoncms Docker.
Development Vs Production
There are three docker compose files:
docker-compose.yml defines the base config; things that are common to both development and production.
The second file
docker-compose.override.yml defines additional things for development enviroment e.g. use
default.docker-env enviroment variables and mount emoncms files from local file-system instead of copy into container.
The third file
docker-compose.prod.yml defines production specific setup e.g. expose port 80 and copy in files instead of mount. The production docker-compose file is
docker-compose.prod.yml instead of
docker-compose.override.yml when the Emoncms Docker contains are ran as 'proudcution'
This setup is based on the recomended Docker method, see Docker Multiple Compose Files Docs.
The development enviroment with the base + override compose is used by default e.g:
$ docker-compose up
To run the production compose setup run:
$ docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
Files, storage & database info
Infomation about how files and databases work in Emoncms Docker.
By default when running the development compose enviroment (see above) Emoncms files are mounted from the host file system in the
emon_web Docker container at startup. This is desirable for dev. For production / deployment / clean testing run production docker compose (see above). This will copy emoncms files into the docker container on first run. Any changes made to the files inside the container will be lost when the container is stopped.
Storage for feed engines e.g.
var/lib/phpfiwa are mounted as persistent Docker file volumes e.g.
emon-phpfiwa. Data stored in these folders is persistent if the container is stopped / started but cannot be accessed outside of the container.
/var/lib/mysql/data is mounted as persistent Docker volumes e.g.
emon-db-data. Database data is persistent if the container is stopped / started but cannot be accessed outside of the container.
Useful Docker commands
Show running containers
$ docker ps
Stop / kill all running containers:
$ docker stop $(docker ps -a -q) $ docker kill $(docker ps -a -q)
Remove all containers:
e.g. emon_web, emon_db
$ docker rm $(docker ps -a -q)
Remove all images:
e.g. Base images: php-apache, mysql, Ubuntu pulled from Dockerhub
$ docker rmi $(docker images -q)
Attach a shell to a running container:
$ docker exec -it emoncmsdocker_web_1 /bin/bash