Guide to the local installation of datacat

For users (without development environment)

To test the functions of datacat locally, no programming knowledge is required. If an insight into the source code is desired, please look into the second part of this tutorial.

The following is required for installation:

• Docker for Windows
• git
• JDK 15 / 15.0.1 / 15.0.2

Installation

Framed commands with a $ are to be executed in the cmd (execution without the $)

1. create folder in which datacat installation files should be stored
2. start Docker Desktop
3. open cmd (command prompt) via Windows search bar
4. navigate to the created folder:

$ cd path/to/folder

If command does not work: execute E: (drive name, E as an example) once before to change to the desired drive.

5. clone the project (execute command in cmd)

$ git clone https://github.com/dd-bim/datacat-stack.git

6. navigation to the subdirectory

$ cd datacat-stack

7. rename files

$ ren env.example.txt .env

$ ren docker-compose.override.example.yml docker-compose.override.yml

8. customizing docker-compose.override.yml

Right click on File -> Open With -> Editor -> in each of these lines remove the # at the beginning -> Save and Close

# api:
# environment:
# - spring.mail.username=postmaster@my.domain
# - spring.mail.password=mypassword
# - spring.mail.properties.mail.smtp.auth=true
# - spring.mail.properties.mail.smtp.connectiontimeout=5000
# - spring.mail.properties.mail.smtp.timeout=5000
# - spring.mail.properties.mail.smtp.writetimeout=5000
# - spring.mail.properties.mail.smtp.starttls.enable=true

9. download up-to-date files

$ docker compose pull

10. load files into Docker

$ docker compose build

11. start Datacat in Docker

$ docker compose up -d

The local datacat instance should now be accessible in the browser via localhost:3000 (can take up to a minute the first time it is started). The login is done with the username 'admin' and the password 'changeme'. If desired, the password can be customized in the .env file (in the first line).

This datacat instance can only be used for local testing of catalog usage. Registration of new users or simultaneous editing of the catalog are not available.

To stop the application, the Docker Desktop interface in the 'Container/Apps' tab can be used to stop the 'datacat-stack' container and start it up again if needed. The created catalog elements will be preserved.

---

For developers (with development environment)

So that the two components can be tested mutually and developed further together, they can be linked together. The following notes help with the linking during development.

recommended IDE: Visual Studio Code (VSC)

• required extensions:
  • Docker
  • Java Extension Pack
  • JavaScript and TypeScript Nightly
  • Lombok Annotations Support for VS Code

must also be installed for development:

• Docker for Windows
• JDK 15 / 15.0.1 / 15.0.2
• Node.js
• Maven

datacat API:

1. clone the project datacat to a local folder
2. install dependencies

$ mvn clean install

3. restart project if needed (Ctrl+ Shift + P: Java: Clean Java Language Server Workspace).
4. Configuration of the docker-compose.yml file: The datacat API Service needs credentials for the admin account of datacat and for the neo4j databease:

datacat.users.admin.password=
spring.data.neo4j.username=
spring.data.neo4j.password=

4. create Docker images and containers:

$ docker compose up -d

possible problems when setting up the project:

• mvn not found -> Maven not installed
• download of images fails -> possibly configure proxy in Docker (see Docker Docs)

datacat editor

1. clone the project datacat-editor to a local folder
2. install dependencies

$ npm install

3. start the editor

$ npm start

The login is now functional due to the connection to the API, so you have access to all pages of the editor. The login is done with the username "admin" and the password customized in the docker-compose.yml file. The editor can now be modified during runtime. Saving the changes will update the editor in the browser. To view changes to the API, the Docker container must be restarted.

possible problems when setting up the project:

• npm not found -> Node.js not installed
• Firefox sometimes does not show all elements of the interface -> recommendation: use Chrome or Edge for development.