Introduction

Welcome to The Hydraulisc Network's documentation.

This section covers Hydraulisc specifically.

Getting Started

Project Structure

Assuming you used git clone https://github.com/Hydraulisc/foss-hydraulisc.git, your cloned project structure should be as follows:

    foss-hydraulisc/
    ├── middleware/
    │   ├── auth.js - Middleware User Authorization Helper Script
    │   └── forceTextDirection.js - Helper script to force sanitize text inputs
    ├── public/
    │   ├── css/ - Contains various stylesheets
    │   ├── img/ - Contains the default images
    │   └── js/ - Contains the frontend JavaScript
    ├── routes/
    │   ├── api.js - API routes
    │   ├── auth.js - Protected Authorization Routes
    │   └── legal.js - Handles Terms, Privacy Policy and Community Guidelines
    ├── views/
    │   ├── legal/ - Contains the default Terms, Privacy Policy and Community Guidelines
    │   ├── pages/ - Contains the various pages that the server will render
    │   └── partials/ - Contains the partials (headers, footers, other reusables)
    ├── LICENSE
    ├── README.md
    ├── generate-invites.js - Generates invites if the instance is private
    ├── global-variables.json - Default Global Variables file, containing various configuration parameters
    ├── index.js - Main Server file
    ├── migrate-database-v1.js - Legacy Database Migration Script
    ├── migrate-database-v3.js - Legacy Database Migration Script
    ├── package.json - Dependencies
    └── package-lock.json - Dependencies
                    

File Structure Subject to Change

Basic Configuration

Before you can start the local or public server, you must configure some global variables.

These are stored in the global-variables.json file, structured as follows:

    {
        "hostPort": 8800,
        "isPublic": false,
        "inviteMode": true,
        "sessionKey": "test_session_key",
        "protocol": "https",
        "siteDomain": "hydraulisc.net"
    }
                

For now, we'll be covering configuration for a basic local server, changing "hostPort" and "sessionKey".

For the sake of the guide's simplicity, we're changing "sessionKey" to wumieth4ohVeopasee0z, and "hostPort" to 5500.

Your global-variables.json should now look like this:

    {
        "hostPort": 5500,
        "isPublic": false,
        "inviteMode": true,
        "sessionKey": "wumieth4ohVeopasee0z",
        "protocol": "https",
        "siteDomain": "hydraulisc.net"
    }
                

Starting the local server

First, install the dependencies, considering you only just cloned the repo.

$ npm i - you must be inside the foss-hydraulisc root folder to install dependencies.

There are two ways to start the server: Dev Mode, intended for on-the-fly changing, and Live Mode, intended for configured servers.

• Start the local server in Dev Mode:

$ npm run test

• Start the local server in Live Mode:

$ npm run start

If you're following along these docs in a step-by-step manner, we recommend starting the server in Dev Mode.

Admin Setup

If you're following along in this guide, you should now find the local server available at http://IP:5500/. Once again, for the sake of simplicity, we're supposing IP is static 192.167.1.1, so your local domain should look like http://192.167.1.1:5500/.

Congratulations, you just set up your first private and invite-only local Hydraulisc instance!

Configuring your Hydraulisc Instance

Understanding global-variables.json variables

This section provides an in-depth explanation of each configuration value in the global-variables.json file. Understanding these will help you properly secure and personalize your Hydraulisc instance.

hostPort - Type: Integer

hostPort defines the port your Hydraulisc instance will run on. For local development, any unoccupied port (e.g., 5500) will work. For production environments, ensure this port is allowed through your firewall and reverse proxy (if used).

sessionKey - Type: String

protocol - Type: Strict-String

protocol determines both how URLs are generated (e.g., in invites and shared links) and whether session cookies are marked as secure.

• "https" enables secure: true for session cookies. This is required for deployment with TLS/SSL.
• "http" disables the secure flag—use this for local development.

siteDomain - Type: String

siteDomain should be set to your instance's domain name (e.g., hydraulisc.example).

This value is used when generating invite links and shared content URLs in the admin dashboard or frontend. Incorrect values may lead to broken links or users being redirected to a non-existent domain.

isPublic (Type: Boolean) & inviteMode (Type: Boolean)

These two keys control how users can register on your instance:

• "isPublic": false, "inviteMode": true → Invite-only mode: Users must be invited to register.
• "isPublic": false, "inviteMode": false → Private instance: No one, not even you (the first user), can register, unless you created an account before triggering this mode. Useful as an "under attack mode".
• "isPublic": true, "inviteMode": "any" → Public mode: Anyone can register an account. Please note that "any" is not a real or acceptable value, and that "inviteMode" is overriden by the "isPublic": true value.

Changing these settings after setup can impact how your users interact with the site and whether registration remains open.

API Spec

Covers auth, user, and admin endpoints.

Frequently Asked Questions

1. Why can't I register?

Your instance may be set to invite-only or private mode. Ask the admin for an invite, or check your global-variables.json.

2. Where are uploaded images stored?

By default, unless modified, uploads are stored in /public/uploads.