Fork me on GitHub

Command Line Tools

Run the vines command at the command line to get the list of tools.

$ vines 
Usage: vines [options] start|stop|restart|init|bcrypt|cert|ldap|schema

Daemon options:
    -d, --daemonize                  Run daemonized in the background
    -l, --log FILE                   File to redirect output (default: log/vines.log)
    -P, --pid FILE                   File to store PID (default: pid/

Common options:
    -h, --help                       Show this message
    -v, --version                    Show version


The init command is a quick way to get a chat server instance configured and running.

$ vines init wonderland.lit
Created example user alice@wonderland.lit with password secr3t
Created example user arthur@wonderland.lit with password secr3t
Initialized server directory: wonderland.lit
Run 'cd wonderland.lit && vines start' to begin

This creates a directory for the wonderland.lit domain. Chat users on this server will have ID's that end with @wonderland.lit. A self-signed SSL certificate is installed in wonderland.lit/conf/certs that's used to encrypt chat connections.

The name of the directory is actually arbitrary. It doesn't need to match the domain of the chat ID's being hosted.

Linux Errors

If the hostname isn't properly configured in /etc/hosts, we might run into this error.

$ vines init wonderland.lit
Created example user alice@wonderland.lit with password secr3t
Created example user arthur@wonderland.lit with password secr3t
getaddrinfo: Name or service not known

Luckily, the fix is simple. The localhost line in /etc/hosts needs to be configured properly by adding the machine's hostname before the localhost entries.

$ hostname
$ sudo vi /etc/hosts fedora.wonderland.lit localhost.localdomain localhost
$ rm -rf wonderland.lit
$ vines init wonderland.lit


The storage engines supported out of the box all use bcrypt to securely store user passwords. When we're adding users to the database, we can use this command to generate secure passwords.

$ vines bcrypt secr3t

The hashed output can be copied and pasted into a database field.

$ vines bcrypt secr3t

Running bcrypt on the same password multiple times gives different results. This is normal and is an important property of the bcrypt algorithm. If two users use the same password, their bcrypt hashes won't match, making attacks on the password database much more difficult.


The cert command creates a self-signed certificate that can be used to encrypt client and server connections. All connections to the chat server must be encrypted. There is no clear text, unencrypted mode.

$ vines cert wonderland.lit
$ ls conf/certs/wonderland*
wonderland.lit.crt wonderland.lit.key

The wonderland.lit.crt file contains the public key that can be shared with anyone. The wonderland.lit.key file contains the private key and must be kept secret. Make sure the file permissions allow only the chat server to read this file.


The ldap command is used to test the LDAP settings in conf/config.rb. Add an LDAP connector to a virtual host in the config.rb file and run this command to make sure we can connect properly. The JID prompt is an acronym for Jabber ID, which is the full chat ID of our test user.

$ vines ldap wonderland.lit
JID: alice@wonderland.lit
LDAP connection failed: No such address or other socket error.

This message means the host or port isn't set correctly.

$ vines ldap wonderland.lit
JID: alice@wonderland.lit
User not found with filter:

We connected to the LDAP server, but the user ID and password weren't found. Check that the user_attr LDAP property points to an attribute that contains the full JID of the user. The mail attribute is usually a good choice because chat ID's and email addresses typically match.

If we're using the optional groupdn setting to limit the users allowed to login to the chat server, make sure Alice belongs to that group in the LDAP directory.

The search filter is displayed so we can use it in other LDAP debugging tools if needed.

$ vines ldap wonderland.lit
JID: alice@wonderland.lit
Found user Alice with filter:

Success! Users can now login to the chat server using their LDAP user ID and password.


When using the SQL database storage engine, we need a way to connect to the database and create the tables and indexes. We'll use the schema command to test the following storage settings for the wonderland.lit virtual host.

host 'wonderland.lit' do
  storage 'sql' do
    adapter 'postgresql'
    host 'localhost'
    port 5432
    database 'wonderland'
    username ''
    password ''
    pool 5

We've told the chat server to store data in a PostgreSQL database named wonderland. Let's use the schema command to initialize the database.

$ vines schema wonderland.lit
Various create table messages . . .

With the tables and indexes created, the database is ready to use by the chat server. Running this command again won't hurt anything. The schema objects will only be created if they don't exist.

Database Errors

If the database driver gems aren't installed, we will see this error.

$ vines schema wonderland.lit
no such file to load -- pg

We need to install the pg gem when connecting to a PostgreSQL database. This gem provides the database driver that ActiveRecord uses to make the connection.

$ gem install pg
Fetching: pg-0.11.0.gem (100%)
Building native extensions. This could take a while.
Successfully installed pg-0.11.0
1 gem installed

We'll see this error if the wonderland database hasn't been created yet.

$ vines schema wonderland.lit
FATAL:  database "wonderland" does not exist

The connection to the database server is working, but there's no database yet for the tables. We need to use the PostgreSQL createdb tool before we install the schema.

$ createdb wonderland
$ vines schema wonderland.lit

start, stop, & restart

By default, vines runs in the foreground and logs messages to the console. This is nice for quickly testing configuration changes, but not for running a production chat server. Once we have the server configured correctly, we can run it as a background process with the -d or --daemonize flags.

$ vines -d start
Vines has started
$ vines stop
Vines has been shutdown

When the server is running in the background it writes its process ID to a file in wonderland.lit/pid and its logs to wonderland.lit/log. We can customize where these files are located with the --pid and --log flags.

$ vines -d --pid /var/run/ --log /var/log/vines.log start
Vines has started
$ vines stop
Vines is not running
$ vines --pid /var/run/ stop
Vines has been shutdown

Notice that we needed to tell the stop command where the pid file was located because we moved it to a custom location when we started the server. Without the --pid flag, the stop command thinks the server isn't running because it can't find the pid file in the default location.