dspace-dev-docker

DSpace instant development environment using Docker Compose (Currently for Linux)

What?

This is currently a proof of concept. It aims at offering an easy to install, productivity focused, DSpace developmentenvironment.

How?

This project runs on Docker-compose, setting up two containers: one for DSpace development environment and one for Postgres.The development container should include not only all DSpace's prerequisites but also some tweaks to get faster builds,deployments and better code hot-swapping.

Why?

I believe that setting up a productive development environment for DSpace is non-trivial:The build system is 'OK' in the sense that it gets the job done, but it doesn't feel right for development. A lot of files getcopied around, compressed, decompressed and compressed again.

Maven itself is not prone to doing things incrementally out of the box. IDEs can help but it steel feels hard to get anacceptable configuration that avoids full rebuilds. To top that, having the user running ant tasks after maven to get DSpacerunning ensures that your IDE won't understand the full process.

Anyway, it seems that there are lots of things that can be done to hasten the code -> build -> run -> test cycle but it'skind of messy to do it on your workstation. Having a container that keeps all this customizations in isolation shouldencourage experimenting with further tweaks.

This works on Linux

Docker works on Windows and MacOS too. Most of this 'should' work on Windows and MacOS. The major problem, I believe, are mounted folders. On linux, they just work. On Windows and MacOS, I'm not sure how they are mounted. Docker has been working to improve this integration, but I haven't tested any of this outside linux.

What's in it for me?

Right now, the major advantages of this build are

HotSwap Agent integretion, so you can update recompiled classes without restarting tomcat. This should be a MAJOR timesaver while developing.

Skip jar scanning on Tomcat startup configured by default. This should halve tomcat launch time

Launch tomcat contexts in parallel. This should make it faster, maybe

Keep your workspace clean, by putting all of DSpace development dependencies in a container. No more having postgres and tomcat running locally for no reason.

Seamless filesystem integration (in linux) makes working with the mounted source folder feel just like local development. Avoid the nightmare of running mvn package on a VirtualBox or NFS shared folder (which takes forever) while being able to easily edit source files in an editor running on the host machine.

You should end up with the folder structure that dspace-dev-docker expects:

dspace-dev-docker
|-- dspace-src
|-- dspace-build
+-- m2-repo

If you were to change this names, be aware that changing dspace-dev-docker to something else will affect the 'attach' command later on. If you change dspace-src, dspace-build or m2-repo to a different name, be sure to check those names in the docker-compose.yml file under the volumes settings so that they are mapped correctly.

<!-- -->

If you fail to create dspace-src, dspace-build and m2-repo folders, Docker will create them for you on startup, but belonging to the ROOT user. Make sure to change ownership of this folders to your user (e.g., sudo chown -R youruser:youruser dspace-src dspace-build m2-repo) or compilation and ant tasks will fail

<!-- -->

When you run ant tasks, this container expects dspace to be installed on the /srv/dspace folder. Edit your local.cfg file in the dspace-src folder so that dspace.install.dir=/srv/dspace. Otherwise, running fresh_install will fail.

<!-- -->

You will need to change the db.url property in the local.cfg file to db.url=jdbc:postgresql://postgres:5432/dspace to make the database connection work (notice postgres is used instead of localhost). The expected DB credentials are dspace:dspace for the dspace database.

Launch Docker compose and let the magic happen. It takes a while to download the first time you run it.

docker-compose up -d

Once launched, you should be able to attach to the container's bash process. This will get you into a 'developer' account

docker attach dspacedevdocker_dspace-dev_1

Doing things

Once inside the container, you can do dspace things, as packaging the project. The container should start on the dspace-src folder. E.g: lets compile DSpace with Mirage2 enabled

mvn -Dmirage2.on=true -Dmirage2.deps.included=false package

Once compiled, the 'task' alias is available. This basically runs ant using the build.xml found in /srv/dspace-src/dspace/target/dspace-installer/build.xml, so that you don't have to move back and forth to that folder. So, you can run from anywhere

task fresh_install

Also, an alias to the dspace binary is available, so you can run from anywhere

dspace create-administrator

The tomcat alias is also available, to quickly launch and stop tomcat. The catalina.out alias lauches 'tail' to follow tomcat's log file.

Rough Edges

"Nothing works out of the box. This project sucks. Your Dockerfile is a mess. You suck. We hate you"

-- Everyone, all the time

As this project hasn't caught much traction and I'm probably the only one using it, there are some annoyances to be taken into account. Some known, some unknown. Hopefully, they will be eventually get ironed out, but, for the time being, keep these issues in mind:

Now (only) works with DSpace 6.0! It used to work on DSpace 5.5

Currently, some things are harcoded inside Tomcat configuration to work with DSpace 6.0. Check $CATALINA_HOME/conf/Catalina/localhost/ xml files and change the 6.0 references to whichever version you need. These files are meant to do a little magic, avoiding the extra ant-update step. If you can't fix this, try deleting those files and run the copy_webapps command alias to copy all webapps to tomcat's webapps folder

UID is ironed into the Dockerfile

To get things running smoothly, the developer user of the container should match in UID to your current user. It is hardcoded to 1000. If you need to change this (say, your UID is 1009), you will have to rebuild the image with your user ID. Perhaps you can create your own layer to only change this, but, if you want to get up and running quick and dirty, uncomment the following lines in the Dockerfile. This should change the user's UID.

Only xmlui and solr are currently running

Yes, I will get this fixed eventually, if somebody asks for it. If you check $CATALINA_HOME/conf/Catalina/localhost you will notice that just two files exist. xmlui.xml and solr.xml. This should be enough to get a running DSpace instance with XMLUI interface. You can create the missing files to get the other services running, or copy the webapps you need into $CATALINA_HOME/webapps folder. The copy_webapps alias copies all the webapps from /srv/dspace/webapps to that folder. Not thoroughly tested, though.