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. It requires very little resources; a typical Data Crow server instance can cope with just having 1024MB of memory available.
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 an example is shown for the Data Crow start command;
- 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.
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 of the first administrator. They are only used to create this user when the database has no users yet. After that they are ignored, so you can remove them from the start command. The server itself does not log in as a user. 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: (user rwaals, pw 123456): -credentials:rwaals/123456
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 the 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. It also applies to the API server and the image server. Without it the web, API and image server listen on all addresses. With -bindto:127.0.0.1 they can only be reached through a reverse proxy on the same machine.
- hostname: the name of the server (or its IP address). This parameter is required. 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.
- tls: encrypts the connection of the full client with the server. The server creates a certificate for itself (in the security folder of the user directory), or you use your own with -tls_keystore:<file> and -tls_keystore_password_file:<file>. The server then only accepts encrypted connections from the full client. The image server accepts both encrypted (full client) and plain (a web client behind a proxy) connections.
- appserver_bindto: the address the application server (used by the full client) listens on. With -appserver_bindto:127.0.0.1 the full client can only connect from the server itself, for example through an SSH tunnel, so the application server cannot be reached from the internet.
- trusted_proxies: the IP address(es) of a reverse proxy in front of the web and API server, separated by commas (for example -trusted_proxies:127.0.0.1). Behind a proxy every request seems to come from the proxy. For requests from the addresses you give here, Data Crow takes the real address of the user from the X-Forwarded-For header. This is needed for the protection against failed logins, for HSTS (see below) and for users without a password: a request which comes through a proxy which is not trusted is never seen as coming from your local network.
- reset_2fa: -reset_2fa:<username> switches off two-factor authentication for this user when the server starts. Use it for an administrator who lost the phone and the recovery codes, and remove the parameter afterwards.
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/
The web client is described in The Web Client. A language which was added on the server can be chosen on the login screen.
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.
- Encrypted connection (TLS): tick this when the server was started with -tls.
Encrypted connection (TLS). The first time you are asked to trust the fingerprint of the certificate of the server. If it is a different certificate later on, you get a warning. A full client which does not use TLS gets a message after a few seconds that the server needs an encrypted connection. The full client also warns when you connect to a server on another computer without an encrypted connection; you can choose not to be warned again for that server. More about TLS: documentation/data_crow_howto_tls.md.
Same version. The full client and the server must have the same version. If not, logging in is refused with a message which tells which version to install.
Security of the server #
- Addresses which fail to connect repeatedly (failed logins, or programs which are not a Data Crow client, such as port scanners) are blocked for 60 minutes after 5 failed attempts within 10 minutes. This also applies to the login of the web client and the Data Crow Reader app. Addresses in your local network are never blocked.
- Users without a password can only log in from the local network. The automatic login of the web client, when only the SA user without a password exists, also only works from the local network. Set a password for users who connect from outside the local network.
- A login of the web client and the Data Crow Reader app ends after a time without activity. The times are set in the security settings of the server.
- The maximum size of attachments is checked by the server, also for the full client. Pictures larger than 50 MB or 50 megapixels are refused.
- The internal administrator account of the server cannot be used to log in.
- When the web client is used over HTTPS, browsers are told to always use HTTPS for it (HSTS, for one year). Behind a reverse proxy this only works when you start the server with -trusted_proxies and the proxy sends the X-Forwarded-Proto header, which Caddy does by default.
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.