In this article we will cover the main prerequisites for successfully creating running a censhare server locally using Homebrew. The full list of prerequisites and other dependencies can be found here.

Prerequisites

Install the following developer tools on your computer:

  1. Install brew
    • Got to brew.sh  and follow the instructions.
  2. Install Git 

    • In a terminal window, execute the command 

      brew install git
  3. Install n 

    • In a terminal window, execute the command 

      brew install n

    • Install node lts 

      n lts

    • Choose your node version 

      n
  4. Install Yarn 

    • In a terminal window, execute the command 

      brew install yarn
  5. Install Java 11 JDK 

  6. Install jenv 

    You only need to install jenv if you want to run censhare versions prior to 2019.1 locally, as these require Java 8. Otherwise, you can skip this step!

    • In a terminal window, execute the command 

      brew install jenv && mkdir ~/.jenv/versions

    • Add the Java 11 to the jenv with the command 

      jenv add <path_to_Java11>
    • If you are unsure about the correct path, you can check it with the command usr/libexec/java_home -v 11.
  7. Install the database
    • There are two database solutions you can run with censhare. Select the desired one and follow the installation/setup:
    • PostgreSQL: Install from postgresapp.com .
    • Oracle with Docker: Follow the instructions from  this article.

Configure Git & clone the censhare project locally

  1. Git configuration
  2. Create local repository
  3. Create working directory from local respository
  4. Add Git hooks
  5. Add helpful Git aliases

Bash aliases

For a quick navigation into the different parts of the censhare project, make sure to set up the following aliases: 

alias css-log="less +F ./censhare-Server/work/logs/server-0.0.log"
alias css-clean="rm -rf ./censhare-Server/work/runtime.SERVER_NAME/ && rm -rf ./censhare-Server/work/live/ && rm -rf ./censhare-Server/work/classes/ && rm -f ./censhare-Server/work/logs/*.lck"
alias css-build="./censhare-Server/bin/build.sh clean init jar"
alias css-stop="./censhare-Server/bin/StopServer.sh"
alias css-start="./censhare-Server/bin/StartServer.sh SERVER_NAME"
alias css-docs="./censhare-Doc/bin/build.sh clean release.doc.dev"
alias css-rebuild="css-stop && css-build && css-start && css-log"
alias css-release="./censhare-Client/bin/build.sh clean init release.mac"
alias css-kill='jps | grep CenShareServer | sed -E '\''s/ CenShareServer//'\'' | xargs -I {} sh -c '\''kill -9 {}'\'''

Important

Replace the SERVER_NAME tag, with the name that you chose for your server in config files. Use the absolute path in all aliases to be able to run them from any folder.


Sublime text

This step is optional.

  1. Install Sublime Text from sublimetext.com.

  2. Create the subl command: 

    ln -s "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" /usr/local/bin/subl

  3. Setup Sublime Text as default bash editor. The attribute -w causes the subl command to not exit until the file is closed: 

    export EDITOR='subl -w'

Build the project

  1. Go to the local project folder: 

    cd ~/DIR_NAME/censhare-product

  2. Build the project: 

    css-build

  3. Download and unzip the patch_files.zip file.

  4. Copy the files launcher.patch and server.SERVER_NAME.patch to DIR_NAME\censhare-product\censhare-Custom\censhare-Server\app\config\.
  5. Create a config directory if it is not present in the app/ directory.
  6. Copy the file config.SERVER_NAME.patch to ~/DIR_NAME/censhare-product/censhare-Custom/censhare-Server/app/services/database/.
  7. Create the services and database directories if they are not present in the database/ directory.
  8. Go in the file ~/DIR_NAME/censhare-product/censhare-Server/app/config/insert-data.xml. Find <server_defs><server_def name="master" .../></server_defs>, and Replace name="master" with name="SERVER_NAME".

Important

  1. Replace the SERVER_NAME tag with the name of your choice for the server, in the following:
    • The name of the server.SERVER_NAME.patch file and from its contents
    • The name of the config.SERVER_NAME.patch file
  2. Depending on the editor of your choice, quotes (“…”) in both files can be converted to curly quotes (“…”), which might cause issues on the server startup. Therefore, make sure that the quotes in both files are set as expected.


Create database

  1. Create a psql alias: 

    sudo mkdir -p /etc/paths.d && echo /Applications/Postgres.app/Contents/Versions/latest/bin | sudo tee /etc/paths.d/postgresapp

  2. Restart the Terminal

  3. Check if the Postgres server is running. You can do it via the Postgres App (elephant icon) in the menu bar:

    • If the Terminal states psql: command not found, you must add Postgres to the PATH variable manually. Use the following command and replace the <EXACT_VERSION> tag with the Postgres version that is running on your machine: 

      export PATH="/Applications/Postgres.app/Contents/Versions/<EXACT_VERSION>/bin:$PATH"
    • To exit the psql  mode from the command line, type \q . The combinations Ctrl+C , exit or quit  do not work!

  4. Create the user and the database: 

    psql -U postgres -f ~/DIR_NAME/censhare-product/censhare-Server/database/postgresql-create-user.sql

  5. Create the database structure: 

    psql -U corpus -W -d corpus -f ~/DIR_NAME/censhare-product/censhare-Server/database/postgresql-create-db.sql

    If asked, enter the password corpus .

Install Image-Service-Tools

Install the latest package of Image-Service-Tools from the censhare repository (censhare-ImageService-tools-<yyyy>.pkg).

Start the local censhare server

  1. Check if your <censhare-username>  points to the localhost address: 

    ping -c 1 <censhare-username>

    The IP address should be 127.0.0.1 - if the address is different, edit the /etc/hosts and add your username right after the localhost entry: 

    127.0.0.1 localhost <censhare-username>

  2. Create the work directory: 

    mkdir DIR_NAME/censhare-product/censhare-Server/work/
cp -rf DIR_NAME/censhare-product/censhare-Server/work-template/* DIR_NAME/censhare-product/censhare-Server/work/

  3. Start the server: 

    css-start

  4. Open the logs: 

    

Build & start the censhare Admin Client
  1. To build the Admin Client on your local machine, execute 
    

    css-release
    

  2. Grant ownership permissions for your user to the following directory. If the directory does not exist, create it first: 
    

    sudo chown myusername -R ~/Library/Preferences/censhare
    

    Incorrect permissions on this directory prevent you from opening any of the censhare clients.
  3. Create the following directories, if they do not exist: 
    

    mkdir ~/Library/Preferences/censhare/v4
mkdir ~/Library/Preferences/censhare/v4/hosts
    

  4. Copy the hosts.xml file to the directory
    

    ~/Library/Preferences/censhare/
    

  5. Go to ~/DIR_NAME/censhare-product/censhare-Client/release/mac/ and open the censhare Admin Client app.
  6. Open Configuration/Services/Module service/Configuration.
  7. In the Server Name dropdown, select the server name set in the SERVER_NAME tag earlier, and select Service enabled.
  8. Select Development Mode and TypeScript compilation.
  9. Write in the NodeJs command field, enter node and click the OK.
  10. Open the Server actions menu (gear icon ⚙️  on the top panel) and execute Synchronize module assets (required & optional).
  11. Open the Server actions menu and execute Update server configuration.
Access censhare Web
  1. Access censhare Web in your browser: https://localhost.censhare.com:9443/censhare5/client/
  2. After ensuring that everything works fine, open the file ~/DIR_NAME/censhare-product/censhare-Custom/censhare-Server/app/config/launcher.patch and uncomment the lines 11-13. This allows the automatic database updates to be executed on server start up.
Troubleshooting
If something does not work properly ask your colleagues, or post an open question to the #dept-dev-all channel in Slack.
Helpful commands
  • List running processes 
    

    ps
    

  • Stop a process 
    

    kill -9 <proccess_id>
    

Debug settings
  • Java 5 to Java 8: 
    

    -Xrunjdwp:transport=dt_socket,server=y,address=8001,suspend=n
    

  • Java 9 and later: 
    

    -Xrunjdwp:transport=dt_socket,server=y,address=*:8001,suspend=n