Development Install

Description

This document describes how to get a source checkout running to be able to develop for Plone Intranet.

We assume you want to do some work on ploneintranet. Here is what you need to do to get yourself set up.

Please subscribe to the developer mailing list and tell us what you want to do. It might already be done in enterprise edition, in which case we can talk about backporting that work to community. Or it might not be already done, in which case we can talk about the best way to do the feature.

Prepare the Operating System Environment

Plone Intranet has quite a number of OS-level dependencies:

  • ruby (for docsplit) and docsplit
  • java (for Solr)
  • redis-server

We maintain an exact description of these requirements in the form of a Ubuntu based Dockerfile_, which you can use either to build a Docker container, or to set up your own Ubuntu virtual.

To build a Docker container with Plone Intranet inside:

docker build -t ploneintranet .

This requires docker to be available, see the `Docker installation docs`_.

Manual OS preparation

You can skip this section if you use the provided Dockerfile.

If you want to prepare your system environment manually, please use the Dockerfile_ as a reference. YMMV.

Make sure you have the OS-level packages you need to build Plone, this can be achieved using install.plone.dependencies.

In addition, for the Plone Intranet file preview functionality, you need docsplit. On Ubuntu:

sudo apt-get install ruby
gem install docsplit

You will need some other tools installed for docsplit. See the `docsplit installation instructions`_. Note that Libre Office is mentioned as optional there, but in Plone Intranet we require it.

Solr is a required component. This will be built using buildout, but requires Java to be available.

Redis is a required component. This is not built with buildout, but expected to be available as a system service:

sudo apt-get install redis-server

Setting up Your Development Environment

Set-up a development environment:

git clone https://github.com/ploneintranet/ploneintranet
cd ploneintranet
virtualenv -p python3.7 . --no-setuptools
bin/pip install -r requirements.txt
bin/buildout -c buildout.cfg

Note

If you’re a member of the Quaive team, please use the private Quaive repo at https://github.com/quaive/ploneintranet instead of the public community repo.

Create a new Plone instance

The following steps activate Plone Intranet and sets up some demo users and workspaces so you can see what’s possible.

  1. Create a new Plone instance.
  2. In the ZMI, go to portal_setup > import. Select Plone Intranet: Suite : Create Testing Content and choose Import all steps at the bottom of the page.
  3. You can now go to the site at http://localhost:8080/Plone. However, don’t do this logged in as admin in the ZMI. Logout, or open a new browser window (use Chrome).

The test content setup created some users. Login with one of the following:

Username Password Permissions
allan_neece secret Default user
christian_stoney secret Workspace admin with more permissions
alice_lindstrom secret Not a member of any workspaces

Those passwords are not actually secret, they’re just the word “secret” without quotes!

Note

If you end up with an empty and/or unthemed site, you probably installed Plone Intranet Suite via the Plone Add-ons configuration screen.

If you want an empty site, you can install Plone Intranet: Suite via the Quickinstaller. In that case you will also have to install Plone Intranet:  Theme - we ship with a default theme but it’s not automatically installed.

Please read the section on User Profiles to learn how you can manage users.

You may also want to create the database tables for the collective.mustread addon. For this, visit http://localhost:8080/Plone/@@init-mustread-db For more information and information on how to integrate with collective.auditlog visit the collective.mustread documentation.

Running tests

See Testing

Alternative install strategies

Instead of the normal procedure listed above, alternative buildout strategies for special cases are documented below.

Note

You can safely ignore the instructions below.

Use coredev.cfg instead of buildout.cfg.

The theme currently only works when enabling the development-mode in the resource-registries, then pressing develop css and develop javascript for the bundle ploneintranet and pressing Save.

Due to a limitation of zc.buildout coredev.cfg has to have a copy of the same checkouts as buildout.cfg.

Instead of the steps listed above you can alternatively use the supplied docker.io scripts. This will provide you with an isolated chroot-like application container. The source codes will live outside the container in your normal home directory, so you can easily edit them with your favorite IDE.

  1. Install Docker on your development workstation
  2. git clone git@github.com:ploneintranet/ploneintranet.git
  3. cd ploneintranet
  4. sudo make docker-build will prepare the docker image
  5. sudo make docker-run will launch the docker image and give you a shell inside

Note

Make sure you are inside the docker container (usually your prompt changes!)

  1. make will fetch the ploneintranet compiled javascript bundle
  2. make devel will run the development buildout
  3. bin/instance fg will run the Plone instance, which you can access on localhost:8080.

This is an experimental setup. YMMV. The provided configs re-use your .bashrc, re-use a /var/tmp buildout cache, re-use your ssh agent etc. You might have to disable or reconfigure some of that if you’re not on a Linux host.

If you use boot2docker on Mac OS X (Windows not tested) follow the instructions below.

The packages installed here cover not only normal Plone development, but also anything needed to work on the prototype or the documentation.

Once you’ve completed all these steps and have the installation working, you can exit via ^C (end instance) ^D (log out of docker app).

To re-run the instance you only need to sudo make docker-run and then inside the app bin/instance fg.

It’s also possible to run this without sudo.

Cleanup your docker image

issue:
e.g. make commands return a command not found error

Note

If you accidentally doing something wrong outside the container / before you started the container shell, e.g. a “make” command, this may mess up your docker image.

You can clean this up by invoking a:

git clean -fdx

This forces a clean up of your checkout including directories and ignored unversioned files. Make sure you have backups - ** Be careful!**

boot2docker – build issue

issue:
make docker-build and make docker-run are not working with boot2docker.

Running a make docker-build command drops:

docker.io build -t ploneintranet .
make: docker.io: No such file or directory
make: *** [docker-build] Error 1

If you use boot2docker on Mac OS X (Windows not tested) there are now alternate make commands in the Makefile:

To create the docker build, instead use:

  1. Install boot2docker on your Mac or Windows machine.
  2. git clone git@github.com:ploneintranet/ploneintranet.git
  3. cd ploneintranet

Note

with boot2docker you must run ther next commands without sudo !

Remember to make sure you run them inside the docker container shell!

  1. make boot2docker-build will prepare the docker image
  2. make boot2docker-run will launch the docker image and give you a shell inside

boot2docker – docker environment not initialized

issue:

running a docker command drops:

docker error: /var/run/docker.sock: no such file or directory

You may need to initialize your docker environment variables properly to run a docker command successfully!

Export the boot2docker environment properly to run the docker-build process

  1. start boot2docker using “boot2docker up”

  2. The boot2docker VM is now running

  3. before “make boot2docker-build” run the command:

    $(boot2docker shellinit) # including the leading dollar character and brackets!

# continue with the build as described above

boot2docker – Service not accessible

issue:
you cannot find any running services under localhost

Use the “boot2docker ip” command to figure out what NAT ip your boot2docker vm is using. ** Use this ip instead of localhost with the expected port!**