This guide is for people who want to hack on Convos.
The first step is to clone the Convos repository. You can either do this directly on github or by running the command below:
$ git clone https://github.com/nordaaker/convos.git
The command above will create a “convos” directory in the current working
directory. The following steps need to be run from the project root, meaning
cd ./convos first.
Once you have the source code you should install the dependencies:
$ pnpm i $ script/convos install --develop
--develop will install dependencies which is only required if you want to
make changes to the files in the
assets/ directory. Note that the
dependencies are installed in
local/lib/. If you want to install them
globally or in your
$HOME/perl5 directy, then use one of these command
$ perl ./script/cpanm --installdeps --sudo . $ perl ./script/cpanm --installdeps .
It is highly suggested that you install an IRC daemon, since many networks will ban you if you reconnect too often. Any IRC compatible server will work, but ircd is a good alternative:
$ sudo apt-get install ircd-hybrid # ubuntu $ brew install ircd-hybrid # osx
The basics of getting the application running in development mode is the command below:
$ ./script/convos dev
The command above is the same as:
$ CONVOS_DEBUG=1 script/convos webpack \ -w lib -w public/convos-api.json -w templates
CONVOS_DEBUG will print extra low level debug information to STDERR, which is
useful to discover bugs. The
-w switch is for watching different files and
directories for changes and reload the web server automatically.
convos dev will automatically pick up any certificated files in the
root of your project. This can be useful if you want to work on some features
that require “https”. A self-signed certificate is often not enough, so we
suggest using mkcert to set up local
After you have installed
mkcert you can simply run the following commands to
get a secure connection:
$ mkcert localhost $ ./script/convos dev
The default address for the secure server will be https://localhost:3443/, but you can change that:
$ ./script/convos dev --listen https://localhost:8443
The command below will create production assets, which will be used when you start the production version of Convos:
BUILD_ASSETS=1 prove -l t/production-resources.t
The cpanfile is
used to document all the requirements, while the
Makefile.PL file is
generated from the content of the cpanfile.
The lib directory contains all the Perl source code.
The public directory contains fonts and images which can be downloaded through the Convos web server.
The script directory contains the main application file (convos) and helper scripts. The important part here is that every file which has the executable bit set will be part of the final CPAN distribution.
The t directory contains the test files for the Perl code.
.------. ____| Core | .--------._/ '------' | Convos | '--------' .-------------. \_______| Controllers | '-------------'
.---------. ___| Backend | .------._/ '---------' | Core | '------ .------. .-------------. .---------. \_____| User |__| Connections |__| Dialogs | '------' '-------------' '---------'
Convos::Core is the heart of Convos. The core takes care of connections, dialogs can persist to a backend and provide hooks for plugins.
The design makes Convos a multi-user application, that can persist to any backend (memory, file storage, redis, …) and connect to any chat server, as well as keeping any number of dialogs active.
The way the backend is hooked into the rest of the object graph is by events. Any user, connection or dialog can emit new events that the Backend can choose to persist to storage. The default backend is a file-based backend, which enables Convos to be started without any external database.
Convos has an OpenAPI powered REST API. The specification is used to both generate perl code for validation, and to generate documentation. Resources:
TODO: Need to document the WebSocket API as well.
Any contribution is more than welcome! Examples: If you find typos on this web page or find something annoying, then please tell us.
We welcome pull requests, but any form of patches are better than nothing. The pull request does not need to be complete either, but it is more likely to get merged if it includes tests and documentation updates.