SETUP

SETUP

This guide will help you execute Construct for the first time. If you are building from source code and have not already done so please follow the instructions in BUILD before continuing here.

NOTES

• We will refer to your server as host.tld. For those familiar with matrix: this is your origin and mxid @user:host.tld hostpart. Your well-known delegation is not relevant here.

• If you built construct yourself as a standalone build you will need to add the included library directories before executing: export LD_LIBRARY_PATH=/path/to/src/deps/boost/lib:$LD_LIBRARY_PATH export LD_LIBRARY_PATH=/path/to/src/deps/rocksdb:$LD_LIBRARY_PATH

PROCEDURE

If you are running a container see the non-interactive setup section.

1. Execute.

   There is one argument: <origin> described in the notes above (your host.tld).

   bin/construct host.tld
   

   There is no configuration file. Configuration persists in the database found at the default installed path (i.e. /var/db/construct/<servername>) which can be overridden with the environment variable $ircd_fs_base_db or $STATE_DIRECTORY.

   Log messages will appear in terminal concluding with notice IRCd RUN.

2. Strike ctrl-c on keyboard:

   The command-line console will appear for interactive setup.

3. Create a general listener socket by entering the following command:

   net listen matrix * 8448 privkey.pem cert.pem chain.pem
   mod reload m_listen
   

   • matrix is your name for this listener; you can use any name.
   • * and 8448 is the local address and port to bind.
   • For non-SSL listeners, omit all of the pem files from the command.
   • privkey.pem and cert.pem and chain.pem are paths (ideally absolute paths) to PEM-format files for the listener's TLS. If you only have two files (e.g. privkey.pem and cert.pem) then repeat cert.pem twice in the command so it takes the place of chain.pem.

   The Matrix Federation Tester should now pass. Browse to https://matrix.org/federationtester/api/report?server_name=host.tld and verify "AllChecksOK": true

   Deleting a listener can be done with the command net listen del i.e. net listen del matrix. Adding a listener with the same name again overwrites it.

4. To use a web-based client like Riot, configure the "web root" directory to point at Riot's webapp/ directory by entering the following:

   conf set ircd.web.root.path /path/to/riot-web/webapp/
   mod reload web_root
   

5. Browse to https://host.tld:8448/

   • Register a user at the console with the command user register <username> <password> as registration through clients is disabled by default.

     🛑 PUBLIC REGISTRATION IS CURRENTLY UNSAFE. To enable public registration, use the command conf set ircd.client.register.enable true

NON-INTERACTIVE

The listener-socket and web-root as described for interactive setup will instead be configured as environment variables prior to execution.

ircd_listen_matrix_host=0.0.0.0
ircd_listen_matrix_port=8448
ircd_listen_matrix_private_key_pem_path=/path/to/my/key
ircd_listen_matrix_certificate_pem_path=/path/to/my/cert
ircd_listen_matrix_certificate_chain_path=/path/to/my/chain
ircd_web_root_path=/path/to/riot-web/webapp/
/bin/construct host.tld

For non-SSL listeners, omit all certificate and key variables.

If you do not have a certificate chain file, repeat the certificate path in its place.

❗ Unlike the interactive setup, this configuration will not be persisted in the database.

👉 Any configuration item within the server can be overridden with an environment variable by replacing any . with a _.

ADDENDUM

• If you are employing a reverse-proxy you must review the apropos section in the TROUBLESHOOTING guide or the server may not operate correctly.

• Logging to files is only enabled by default for CRITICAL, ERROR, and WARNING. It is not enabled by default for the INFO level. To enable, use conf set ircd.log.info.file.enable true.

• Review the performance TUNING guide to get the most out of your deployment.