Data Crow Server

Since Data Crow 4.0 it is possible to run Data Crow as a server. This allows for clients to connect to a single instance of Data Crow.

The server edition is an advanced server, a combined web and application server. This means that users can connect to Data Crow using the thick-client (the Data Crow application) and / or the web client (the browser) . The server allows multiple users, using either of these clients (thick / web) to connect to the server, at the same time. The user management function allows you to set granular user permissions per user, right down to field level.

The server edition is headless, meaning it can run in environments where there is no graphical interface.

The server has several roles, it’s:

• an application server, allowing thick client to connect securely.
• a web server, allowing browsers to connect.
• an API server, allowing other services, external to Data Crow to connect and retrieve information (with your permission only). The web version uses the API as well as the Data Crow Reader App.

Installing the Server
#

To install the server:

• Unzip the zipped Data Crow Server distribution to the installation location.

That’s it – it does not require any further installation. It does require Java version 17 or higher though.

Setting up the Server #

Just as the normal client does need a user folder where it stores the data and settings, the server does so too. You can choose to have the server edition set up a new empty user folder, or, you can choose to use an existing user folder.

Tip: use the thick client to set up the initial user folder – use the client to create users, change the system settings and basically to configure Data Crow to fit your needs. This opposed to the web client, which does not have all features the thick client has.

Running the Server
#

The server has no graphical user interface (GUI) which means it relies fully on the command line. Open the terminal (Linux and Mac users) / command prompt (Windows users) and navigate to the Data Crow Server installation folder.

In the below example I will show <command> for the Data Crow start command;

• None Windows: Java –Xmx1024m –jar datacrow-server.jar
  The –Xmx1024m parameter specifies the amount of memory available to Data Crow. You can change this to another number if necessary.
• Windows: datacrow-server.exe (or the above, either will work)

Now we are ready to start the server.

<command> -userdir:<user folder> –port:<portnumber> –imageserverport:<portnumber> -webserverport:<portnumber> –credentials:<username>/<password>

Explanation:

• The <command> I have explained above, make sure you use the correct syntax for the platform you are using.
• userdir: specifies the user folder location.
  Example (Windows): -userdir:c:/server-data
• port: specifies the main port number for the application server. The default port is 9000. If you do not supply the port parameter, port 9000 will be used.
  Example: -port:9000
  When the server has been started, clients connect by starting the Data Crow Client in client mode (-client parameter).
• imageserverport: specifies the port to use for the HTTP image server. The default is port 8081. If you do not supply the port parameter, port 8081will be used.
  Example: – imageserverport:8081
• webserverport: specifies the port to use for the web server. If not supplied, the web server module will not be started.
  Example: – webserverport:8080
  When started, clients connect to the server as follows:
  https://<server address>:<webserverport>/datacrow
  Example: https://192.168.178.12:8080/datacrow.
• credentials: username and password for the administrator. This is a required parameter for security reasons. The default user for Data Crow is SA with a blank password. It is recommended to set a password for each user when using the client-server setup.
  Example #1 (user rwaals, pw 123456): -credentials:rwaals/123456
  Example #2 (default user): -credentials:SA

A tip on the credentials; you can also supply these within the datacrow.credentials file. When this file is present in the installation folder of the Data Crow server Data Crow will read the credentials from this file and they don’t have to be supplied anymore as a parameter. The file does not exist by default; create the file (a plain text file) and enter the credentials within this file: <username>/<password>.
For example: rwaals/123456

Other, optional parameters:

• bindto: overrules tehe default way Data Crow server binds itself to your IP address. This is only necessary in unforeseen circumstances where Data Crow is not picking up the correct IP address to bind itself to.
• hostname: the name of the server. Useful if you don’t want to use the IP address as the go to address.
• api_address_overrule: this is used to overrule the way Data Crow automatically sets the address for the API server. Using this option you can map the API address to another local port that is used by Caddyfile for example (reversed proxy).
• imageserver_address_overrule: this is used to overrule the way Data Crow automatically sets the address for the image server. Using this option you can map the image server address to another local port that is used by Caddyfile for example (reversed proxy).
• dir: indicate the Data Crow Server installation directory (in case of issues).
• debug: allow Data Crow Server to log extensively.

Checking the Server #

If all is well the Server will reporting something similar to below:

INFO [main] (DcServer.java\:140) – Server has been started, ready for client connections.

INFO [main] (DcServer.java\:141) – Client can connect to IP address 192.168.0.121 on port 9000 and on image port 9001

INFO [main] (DcServer.java\:144) – Listening for CTRL-C for server shutdown.

It specifies the actual IP address as well as the assigned port numbers.
Errors will be displayed directly in the console. Additionally there is the default log file, located in the user folder (data_crow.log).
If you want to debug the server (or see more messages) you can supply –debug parameter on startup.

Stopping the Server #

Press CTRL-C in terminal / command prompt window.

Connecting to Data Crow: (Thin) Web Client #

Connecting to the web server is the easiest option. Navigate, using a web browser, to the server address, like so:

http://<server address>:<web server port>/

For example: https://192.168.178.120:8080/

Connecting to Data Crow: (Thick) Client #

Any installation above 4.0 can connect to a server. It’s a simple matter of supplying the –client command to your Data Crow startup:

In the below example I will show the <command> for the Data Crow client start command;

• For Windows users substitute this with:
  datacrow.exe
• For other platforms use:
  Java –Xmx8096m –jar datacrow.jar
  The –Xmx8096m parameter specifies the amount of memory available to Data Crow. You can change this to another number if necessary.

Connect to server by starting Data Crow as follows (amend the shortcut):

<command> -client

When the client starts the following login dialog is shown:

• Login name: your username (the default user is SA)
• Password: your password (the password for user SA is blank)
• Server Address: the IP address of the Server (see the Server console for the IP address, for example within an internal network the IP could be 192.168.0.10).
• Application Server Port: the port as configured on the server (default is 9000). This setting is remembered.
• Image Server Address: the address of the image server, typically the same address as the server itself.
• Image Server Port: the port as configured on the server (default is 9001). This setting is remembered.

Web Server with SSL Security #

If you want access to your Data Crow collection while on the go, hosting the Data Crow server on a VPS (Virtual Private Server) is a practical and affordable option. A small VPS running Ubuntu with 2 GB of RAM and 100 GB of storage is more than sufficient, and such instances are widely available at low monthly cost.

Setting up the server

Start with a headless Ubuntu VPS — no GUI is needed. Install Java (OpenJDK 21 or higher is recommended), then upload the Data Crow server files and your data directory to the VPS using SCP. Connect via SSH, unpack the archives, and arrange them as follows:

~/datacrow_server
~/datacrow_server/data

Start Data Crow with:

java -jar datacrow-server.jar -userdir:./data -hostname:<IP address> -webserverport:8080 -port:9000 -imageserverport:8082 -apiserverport:8081

To keep the server running after you log off, use tmux: start a tmux session, run the startup command, then detach with Ctrl+B followed by D. The server will continue running in the background.

At this point, Data Crow is accessible at an address such as http://<your-ip>:8080 — functional, but unsecured.

Adding HTTPS with Caddy

To serve Data Crow over HTTPS, you can use Caddy as a reverse proxy. Caddy automatically handles SSL certificate provisioning.

Step 1 — Add a DNS record

Add an A record to your domain’s DNS configuration pointing to the IP address of your VPS. For example, adding a record named my to datacrow.org gives you my.datacrow.org.

Step 2 — Install Caddy

sudo apt update && sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl

curl -1sLf ‘https://dl.cloudsmith.io/public/caddy/stable/gpg.key’ | sudo gpg –dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

curl -1sLf ‘https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt’ | sudo tee /etc/apt/sources.list.d/caddy-stable.list

sudo apt update && sudo apt install caddy

Step 3 — Configure the Caddyfile

my.datacrow.org {
reverse_proxy localhost:8080
}

my.datacrow.org:8083 {
reverse_proxy localhost:8081
}

my.datacrow.org:8084 {
reverse_proxy localhost:8082
}

This maps the web interface, API server, and image server respectively through Caddy.

Step 4 — Start Data Crow with address overrides

Because the API and image server are now being served through Caddy on different external ports, Data Crow needs to be told about the public-facing addresses. Add the following parameters to your startup command:

-apiserverport:8081
-api_address_overrule:https://my.datacrow.org:8083/datacrow-api/api
-imageserverport:8082
-imageserver_address_overrule:https://my.datacrow.org:8084

Caddy transparently translates incoming requests on ports 8083 and 8084 to the internal ports 8081 and 8082. The result is a clean, HTTPS-secured address for your Data Crow instance.