README / Installation instructions

[matanox]

Where are they to be found?!
Thanks in advance

[mpetris]

For up to date instructions please scroll down or click here.

We added a README to the catma6 branch. But it also applies to the master branch which represents the current version online. The README describes the setup with the Eclipse and the IntelliJ development environments but it is also helpful if you just want to run CATMA.

With the master branch:
You would need a running Maria DB 10.1.26 or later (MySQL should work as well).
Apply the setup script db/createCATMA6DB.sql
Edit catma.properties and adjust RepositoryFolderPath1, RepositoryUrl1, TempDir, IndexerUrl1 and GraphDbPath1 and BaseURL and and set RepositoryAuthenticationRequired1 to true.

We use Jetty 9.3.20v20170531 to run CATMA. There is no WAR file on Github that you could just drop in the webapps folder. If you want to give it a try, I could commit a deployable WAR or you setup Eclipse/IntelliJ and build one on your own.

The only thing that might require some work is authentication. These are your options:

1. Do not use authentication at all by leaving RepositoryAuthenticationRequired1 false. You could pass in different users via URL argument. Propbably not useful for production use but handy during development and testing.
2. Use Google accounts. That's the easiest way to get authentication going. You can adjust the Google authentication parameters in the catma.properties file.
3. Setup your own authentication server. We use Forgerock's OpenAM for our CATMA accounts. This is not easy unless you're already familiar with OpenAM and LDAP.

[akaihola]

@mpetris, couldn't your instructions above just be copied into a README.txt in the master branch?

[pablox-cl]

I'm having a hard time following the instructions previously and the ones now in the readme. When it says a stock gitlab installation, it points to a local installation? (locally, in a gitlab instance, or in gitlab.com?)

[mpetris]

@pablox-cl The old instructions are no longer valid (which is why the never got copied into the master branch).
Stock gitlab installation means an installation which you control yourself (not gitlab.com). CATMA needs an admin access to the gitlab. We are trying to get rid of that but currently it's needed for a few usecases. The gitlab installation can be on a different host than the CATMA web application.

[pablox-cl]

Thanks a lot, I'm still a bit lost, but I guess I know where to start now.

[OnlineArts]

I agree with that. I would appreciate getting an up-to-date minimal installation guide. That should not be too complicated if someone is familiar with the setup and environment.

[avvertix]

Hi, I'm also interested in self-hosting instructions. Did anyone succeed in the installation?

[maltem-za]

Hi all, the installation instructions in the README are accurate, but obviously very rudimentary, and it's assumed that you have knowledge about web app artifacts, Jetty, and so on. I'd like to flesh them out, but it's simply not a priority right now. If you have any specific questions, feel free to post them here and I'll try to help you along.

If you're using IntelliJ like me - the repo now contains a .iml project file, as well as Maven and Jetty run configurations in .run, which should help a lot in getting set up. You'll need the "GWT" IDE plugin, optionally also the "Jetty" plugin. Note that the run configurations assume that a catma_local-dev.properties file exists in the /src/main/webapp directory (copy the template and configure as needed).

With Eclipse I will probably be of less help as I haven't used it in a long time, but of course it's possible to get it running with that too (and from past experience can actually be significantly easier to get set up with than IntelliJ).

For the GitLab server you can run it locally as a Docker container, or you can use a remote server, but you need to have admin access (and it should be dedicated to CATMA only).

Another important thing to note is that we are currently using forked versions of gitlab4j-api and org.vaadin.elements. You would need to build (mvn package) the revisions linked in pom.xml, currently on lines #87 and #208, locally and install the JAR files in your local Maven repository using mvn install:install-file -Dfile=<path-to-dependency-jar-file> -DpomFile=<path-to-dependency-pom-file>. The CATMA build won't currently succeed without this.

Lastly, copy the SQLite DB to the SQLITE_DB_BASE_PATH in your properties file, otherwise CATMA won't start.

[Edited 12/12/2023 to update instructions for forked dependencies and some other bits]
[Edited 16/01/2024 to add instructions for the SQLite DB]
[Edited 23/10/2024 to remove mention of the "Vaadin 6-8" IDE plugin for IntelliJ, which was deprecated and isn't actually required]

[avvertix]

Ok, so I'll try and I will post here in case of unexpected problems.

copy the template and configure as needed

I see two block I would get rid of in the template in my configuration: Google OAuth and Recaptcha. Can I just not define the variables or they must be defined with null values?

For the GitLab server you can run it locally as a Docker container,

That was pretty clear

Another important thing to note is that we are currently using a forked version of gitlab4j-api.

Very good to know, so I should build it first

[maltem-za]

@avvertix You can just leave them defined with the placeholder values. Email server and reCAPTCHA details will be needed if you want the signup function to work, but you can log in to CATMA with the GitLab root account or any other email/password-based account that exists on your GitLab server.

[avvertix]

Ok so I was able to build it and deploy on Jetty. I decided to compile manually and not to use an IDE as I wanted to run everything in Docker (Gitlab + Jetty with Catma deploy).

Beside some issues with Jetty and file permission on the various folders I see some errors during the first login, during project creation and when entering a project. Dismissing them seems to work anyway, but in any case here the log file

log.txt

The actions are:

• logging-in for the first time
• creating projects
• entering the last project created by dismissing the error

[maltem-za]

@avvertix There is a recurring error org.gitlab4j.api.GitLabApiException: GitLab is not responding which is at the root of many of the errors in your log file. GitLab can take quite a long time to start up inside of a Docker container - I suspect that this is what caused the errors you encountered.

[maltem-za]

As noted in this related issue, CATMA currently has two dependencies (gitlab4j-api & org.vaadin.elements) that you need to build yourself and install in your local Maven repository (as detailed above) before the CATMA build will succeed.

[GuillaumeFromage]

Oof, okay, just to give an overview of the current hoops you have to currently jump through to get the installation process going:

• You need to manually compile serverside elements

git clone https://github.com/forTEXT/serverside-elements.git
cd serverside-elements
mvn clean compile package

• Note that this process relies on cglib, which is deprecated and not working on openjdk ­>= 17. If you're using debian bookworm, you need to install jdk-11, which mean, you need to add oldstable to your sources.list
• I needed to do a few edits in the elements-demo, to match the version numbers in elements, that's in the submodule serverside-elements
• I finally got a config file working, and a docker instance of gitlab running, but the instance keeps on failing tests. I get that its a nice thing to use gitlab for the admin side for merging stuff, but it really makes it tedious trying to create a dev environment. And my guess is that you have to stick to quite specific versions of gitlab...

Is there a way to tell catma to not test all the things related to gitlab in the build process?

[maltem-za]

You need to manually compile serverside elements

Yes, as noted above. The same is true for gitlab4j-api.

Note that this process relies on cglib, which is deprecated and not working on openjdk ­>= 17. If you're using debian bookworm, you need to install jdk-11, which mean, you need to add oldstable to your sources.list

serverside-elements targets Java 8.
The same is true for the (forked) version of gitlab4j-api that we're currently using. CATMA is switching to JDK 21 with the next release, but that is a separate matter.

I needed to do a few edits in the elements-demo, to match the version numbers in elements, that's in the submodule serverside-elements

Ignore elements-demo and just build elements. I suppose we should just supply the pre-built JARs for the forked dependencies.

I finally got a config file working, and a docker instance of gitlab running, but the instance keeps on failing tests. I get that its a nice thing to use gitlab for the admin side for merging stuff, but it really makes it tedious trying to create a dev environment. And my guess is that you have to stick to quite specific versions of gitlab...

Is there a way to tell catma to not test all the things related to gitlab in the build process?

What was the trouble with the config file?
You can tell Maven to skip tests with -DskipTests=true.