Alfresco content model packaging

[timijntema]

Namens: OPEN.satisfaction
Contact persoon: Silvion Moesan

Op het moment word het content model als XML in een folder in Alfresco gezet. Dit is niet de juiste manier om een Alfresco extensie te packagen. Daarbij mist er Share configuratie die controle geeft over welke velden wel en niet bewerkbaar zijn in Alfresco Share.

Development

• Alfresco SDK4 project aanmaken van het Archetype
• Bestaande model op de juiste plek in de structuur plaatsen
• Test instructies toevoegen
• Productie deployment instructies toevoegen
• Ongebruikte example onderdelen verwijderen uit de structuur

[timijntema]

Ik ben al vrij ver hiermee, maar het leek me netjes om een story aan te maken voor de wijziging.

[sergei-maertens]

Dankje voor het werk tot nu toe, zou mooi zijn als we dit in 1.4.0 meekrijgen (die staat gepland voor release over ongeveer een maand). Ik wacht je nieuwe PR af ;)

[sergei-maertens]

I took a quick look at the PR nevertheless, and have some questions and statements

Open Zaak does not claim to provide/demonstrate how you should deploy Alfresco (for production). I believe the content model is included for two reasons:

• CI - start an Alfresco container so that the CMIS-adapter can be tested properly, with a real Alfresco instance
• Reference - this is the/a content model you can use which is compatible with the Documenten API

Now, we also don't want to imply that what Open Zaak does is the correct or best way, as evidenced by this user story and the PR. However, I'd say that detailed instructions and tooling on how to correctly deploy Alfresco with the custom content model are not in the scope of the Open Zaak application/repository.

Is there a way that we can do the following:

• reduce the changes in this repository to the minimum required to serve the CI/example needs, with the best practices (so using a .jar etc.)
• Maybe have some high level documentation/disclaimer in the documentation (https://github.com/open-zaak/open-zaak/blob/main/docs/installation/config/cmis.rst might be a good place for this?)
• perhaps create a separate repository with the tooling and documentation to build/deploy Alfresco with the custom content model. This could be a repository maintained by OPEN.satisfaction on your own github/gitlab organization, or maybe within the open-zaak organization (that's something I would have to discuss with the technical steering group), and then refer from the Open Zaak documentation to that "reference" or extended documentation.

@joeribekker @TjerkVaags @shazada @aboerma @ericherman - do you have any opinions/input on this?

[timijntema]

Creating a separate repository is a possibility. The reason why I created a SDK 4 alfresco project and placed the contentmodel in it, was to make it easy to use for testing. It's now possible to create a small docker container stack for testing with just one command.

If we only include the model and a context file, it will require more effort to run a quick test. I can remove the information on how to deploy it in a production environment and the docker components for creating alfresco enterprise docker images with the model jar included. This would decrease the number of changes in the repository.

[sergei-maertens]

Yes, the intent was clear to me, and I appreciate the contribution!

The reason why I created a SDK 4 alfresco project and placed the contentmodel in it, was to make it easy to use for testing.

I think you mean manual testing rather than automated testing in this case?

If we only include the model and a context file, it will require more effort to run a quick test. I can remove the information on how to deploy it in a production environment and the docker components for creating alfresco enterprise docker images with the model jar included. This would decrease the number of changes in the repository.

I'm pretty sure you have the better picture of how things should be - I believe only Tahir & Tjerk in this project have deep knowledge of Alfresco. So, I'm totally okay with following your advice/suggestions. If we can make a set up without bloat that's easy to use for both manual testing and automated testing, that would be perfect.

I think the following scenario's is what we should aim for:

Trying out Open Zaak without extensions

docker-compose up

Trying out Open Zaak with CMIS adapter and Alfresco

CMIS_ENABLED=1 docker-compose -f docker-compose.yml -f docker-compose.alfresco.yml up

Running tests on CI with Alfresco

This is covered by https://github.com/open-zaak/open-zaak/blob/main/.github/workflows/ci.yml#L64, so in essence:

docker-compose -f docker-compose.travis-cmis.yml up -d

This would of course require a couple tweaks on the non-Alfresco side of things as well. And perhaps it would be ideal if docker-compose.alfresco.yml can be used for both manual, local testing/experimenting and CI, to reduce duplication.

edit: imo it's fine to pin to 6.2 for example inside this repo, and periodically update that version number. That would probably allow us to drop some build tooling/scripts for which the main purpose appeared to be templating out the Dockerfile. Or, maybe we could use build args for that to keep some parametrization.

[aboerma]

We at Exxellence deploy our Alfresco models via amp files (which zip or jar files). We place these in the alfresco/amps directory after which Alfresco copies the amps content to the relevant folders/files. This setup should translate well to Docker I think.

[timijntema]

@aboerma Deploying as jar is similar. It is also easier to use when deploying on a manually installed environment directly on windows. In that case it is only required to place the jar in a modules/platform folder. With amps you would have to run installation scripts.

Both ways are correct for deploying alfresco extensions. In the end it is just about what is prefered. In the sdk4 project it is possible to change the jar packaging to amp packaging by changing one line in the pom.xml.

@sergei-maertens next Tuesday I will have time to see if I can make a few modifications to satisfy your requests

[timijntema]

When working on this today i noticed the following.

The CMIS url check that is on that field is incompatible with docker hosts. If I add .nl at the end of the host it decides that the url is correct, but it is not very likely that services in a dockercompose stack end with .nl.

Should I create a new story for this? I don't see one yet for this problem.

[sergei-maertens]

@timijntema this is because of the URL validation requiring a domain + TLD. If you define the service as openzaak-aflresco-acs.local in docker-compose, you can use that as .local works as TLD here.

It's an edge case and not something likely to change, as we require URLs to actually look like URLs :-) (principle of least surprise)

[shazada]

I've spoken to @TjerkVaags and our opinion is to have a separate project within the Open-Zaak group just containing the Alfresco SDK4 project. From that project we could create the artifcacts and even an image and publish that one to docker-hub as well which then can be included in the compose file here.

[timijntema]

I assume that means someone who has access should create that repository for me to move the Alfresco model packaging to that repository. @shazada or @sergei-maertens is this something one of you can do?

A few additional questions:

• What method of including the content model do we want to use? A few options are:
  • git submodule
  • docker image to be used by CI
  • jar to an artifactory
• Do we want production ready docker image builds in the separate repository?
• Do we want production ready docker images to be build by CI?

[sergei-maertens]

hi @timijntema - we just discussed this issue in the Technical Steering Group Meeting, and here's the summary + answers to the questions:

• I've created the https://github.com/open-zaak/alfresco-content-model repository where the content model can be placed, The Right Way. You should be able to fork that and I think it would be best to move the contents of PR Feature/931 alfresco model packaging #933 to that repository. The repository layout is up to you to follow best practices, I can't say anything meaningful about that.
• We will get @aboerma to review the work, I'm hoping we can also have @shazada and/or @TjerkVaags take a look since they have in-depth Alfresco knowledge

What method of including the content model do we want to use? A few options are:

Ideal situation would be if we have a Docker image ready for use in this (open-zaak/open-zaak) repository for the CI purposes. We test using docker-compose.

The new repository can be configured to run github actions, so we can automate publishing the images to Docker Hub and/or Github Image registry. We will make it clear from the naming on those repositories that it's only meant for testing (manually locally or automated in CI).

Do we want production ready docker image builds in the separate repository?
Do we want production ready docker images to be build by CI?

No - Alfresco production images are really out of scope for the Open Zaak project. Open Zaak implements the "API's voor Zaakgericht werken" standard, and CMIS is an optional feature as Documenten API storage backend. Open Zaak works perfectly fine without CMIS too. Anything we do with Alfresco in this repository only serves to validate that the feature works as intended, and we basically assume that Alfresco (or another CMIS provider) has been installed and configured by a more suitable party.

In short: the Open Zaak project/community does not want to maintain or oversee production Alfresco things.

[timijntema]

I have moved everything to the other repository. Would @aboerma mind giving it a review?

The repository only requires two secrets to be set up in the openzaak repository for it to push test docker images to the openzaak repository. These are:

• DOCKER_USERNAME
• DOCKER_TOKEN

Since I don't have access, somebody else should set that up.

If the below PR is merged, I will modify the pipeline in this repository to use the new images. Until then, thery are not available

open-zaak/alfresco-content-model#1