First of all, thanks! It's really awesome that you're interested in contributing to Rocket Chat. If this is the first Open Source project you will contribute to, it'd be cool if you read GitHub's excellent guide ["Contributing to Open Source"](https://guides.github.com/activities/contributing-to-open-source/).
## Getting Started
You can find Rocket.Chat repositories [here](https://github.com/RocketChat). If you see some issue you are willing to work on, just comment on it. We will add an [In Progress label](https://github.com/RocketChat/Rocket.Chat/labels/stat%3A%20in%20progress), and that's it! Want a simple task to get you started? [We maintain a list of those](https://github.com/RocketChat/Rocket.Chat/labels/contrib%3A%20easy)!
You can find Rocket.Chat repositories [here](https://github.com/RocketChat). If you see some issue you are willing to work on, just comment on it. We will add an [In Progress label](https://github.com/RocketChat/Rocket.Chat/labels/stat%3A%20in%20progress), and that's it! Want a simple task to get you started? [We maintain a list of those](https://github.com/RocketChat/Rocket.Chat/labels/contrib%3A%20easy)!
**You don't have to write code to contribute!**
We are always looking for help with creating or updating documentation, testing our apps (web, desktop and mobile) and reporting bugs.
**Submitting Pull Requests**
For contributions to code or documentation, you can fork the material, apply your contribution, and submit a [Pull Request](https://help.github.com/articles/using-pull-requests/).
For contributions to code or documentation, you can fork the material, apply your contribution, and submit a [Pull Request](https://help.github.com/articles/using-pull-requests/).
**Submitting Bug Reports**
We appreciate any & all bug reports! Did you find a bug? Reporting is easy! Simply open an [Issue](https://github.com/RocketChat/Rocket.Chat/issues) in the applicable repository.
We appreciate any & all bug reports! Did you find a bug? Reporting is easy! Simply open an [Issue](https://github.com/RocketChat/Rocket.Chat/issues) in the applicable repository.
Here are some suggested things to include, when applicable, which may help us troubleshoot a problem:
* Operating System / Version / Architecture (64 bit?)
* Browser type & Version (if web app), any browser add-ons which may be involved (e.g. AdBlocker, NoScript, etc.)
* Desktop Environment (if desktop app) / Version
* Rocket.Chat edition / Version or [build number](/3.%20Support%2Frelease_version_info.md)
* Rocket.Chat edition / Version or [build number](/2. Getting%20Support)
* Expected behavior vs. Actual behavior (In other words, the "bug")
The above minimal hardware configuration is ideal for corporate or group with up to 1,000 users, up to 300 concurrently active and moderate level of mixed uploads, sharing, and bot activities.
VPS (minimal)
Single Core (2 GHz)
1 GB RAM
30GB of SSD
The above minimal virtual configuration, when not over-provisioned by provider, is ideal for small deployments of up to 200 users, up to 50 concurrently active and mimimal level of mixed uploads, sharing, and bot activities.
VPS (recommended)
Dual Core (2 GHz)
2 GB RAM
40GB of SSD
The above virtual configuration, when not over-provisioned by provider, can accommodate small deployments of up to 500 users, up to 100 concurrently active and moderate level of mixed uploads, sharing, and bot activities.
Really Small office Server (Under $100 on-premise server for small group)
Raspberry Pi 3 or Pi 2 ($35 all-in-one system)
4 Cores 1 GB memory
32GB SD Card ($15)
The above minimal configuration can accomodate a small office or group of up to 50 users and up to 25 concurrently active and moderate level of mixed uploads, sharing, and bot activites. This is based on a managed MongoDB service (such as mlab.com). Running mongo local to a Pi is not recommended at this time.
Ansible helps you build a strong foundation for DevOps.
\- Ansible Inc.
Quick Links
-----------
-[Rocket.Chat official Ansible role](https://galaxy.ansible.com/detail#/role/6478)
-[Rocket.Chat official Ansible role](https://galaxy.ansible.com/RocketChat/Server/#readme)
-[Ansible official install guide](http://docs.ansible.com/ansible/intro_installation.html)
About
...
...
@@ -60,7 +60,7 @@ So, now you've got Ansible installed, you can get ready to deploy Rocket.Chat!
\- Ubuntu 14.04 LTS
\- Ubuntu 15.04
Future releases of the [official Rocket.Chat Ansible role](https://galaxy.ansible.com/detail#/role/6478) will include other Linux distributions/releases and other operating systems. If you'd like to see your OS of choice supported, feel free to [raise an issue](https://github.com/RocketChat/Rocket.Chat.Ansible/issues) to ask if it can be added.
Future releases of the [official Rocket.Chat Ansible role](https://galaxy.ansible.com/RocketChat/Server/#readme) will include other Linux distributions/releases and other operating systems. If you'd like to see your OS of choice supported, feel free to [raise an issue](https://github.com/RocketChat/Rocket.Chat.Ansible/issues) to ask if it can be added.
### Inventory set-up
Make a directory somewhere, perhaps in your home directory, or somewhere you keep Git repositories or code. It doesn't really matter what it's called, but for example's sake, we'll call ours `ansible`:
...
...
@@ -108,9 +108,25 @@ You can download roles you want to use using a commandline tool that was install
First off, our roles need somewhere to live, so, let's make a `roles` directory:
`~/ansible $ mkdir roles`
Then, we need to create a `requirements.yml` file that will describe to `ansible-galaxy` how we want to fetch the role. So, create and open the file `roles/requirements.yml` using your favorite editor.
The contents of `requirements.yml` will vary based on which version of Ansible you're running.
Run `ansible --version` to find out.
If you're running Ansible 1.9.4, paste the following into your `requirements.yml`:
``` yaml
-src:RocketChat.Server
version:master
```
If you're running Ansible 2.0, paste the following into your `requirements.yml`:
``` yaml
-src:RocketChat.Server
version:v2.0
```
Next, let's fetch the Rocket.Chat Ansible role using the `ansible-galaxy` command:
*Note: This works also works on Firefox for Android and the desktop browser.*
Point the browser on the Firefox OS device to your Rocket.Chat URL (e.g. https://demo.rocket.chat), then add ````/fxos```` (e.g. https://demo.rocket.chat/fxos) and press OK/enter. You will be prompted to install the app.
***
# Developers
1. Make sure you have ````adb```` (android debug bridge) installed on your PC
2. Enable developer mode on the mobile device
3. Start your Firefox browser on the PC and connect your device
4. Enter the Firefox WebIDE (Shift + F8 or go to Extras -> Web Developer -> WebIDE)
5. "Project" -> "Open hosted app"
6. Enter the path to the Rocket.Chat manifest.webapp **on your server**, e.g. https://demo.rocket.chat/manifest.webapp - then press OK
7. You should now see the icon and description inside WebIDE. Press the play button on top to install it on your device
***
# Admins
You want to use a custom URL to your Rocket.Chat, or maybe a custom icon and description?
Just edit the **manifest.webapp** file in the **/public** folder of the meteor project.
For more info, have a look at the [Firefox OS documentation](https://developer.mozilla.org/en-US/Apps/Build/Manifest).
Make sure you have docker and docker-compose installed and operational.
Note: as stated by Docker, docker-compose is [not yet recommended for production use](https://docs.docker.com/compose/production/) at this time.
Look for the [`docker-compose.yml`](https://raw.githubusercontent.com/RocketChat/Rocket.Chat/develop/docker-compose.yml) file at the top level of the [Rocket.Chat Git repo](https://github.com/RocketChat/Rocket.Chat). This is the ONLY file you will need from the repo. You can create this file on your own machine by copy and pasting the content.
Open it with an editor and modify:
*`ROOT_URL` to match your domain name or IP address
Mongo supports 24 x 7 operations and live backup. You should not need to restart it too frequently. See [mongodb documentations](https://docs.mongodb.org/manual/) for proper operation and management of a mongo server.
Start Rocket.Chat by single command:
````
docker-compose up -d rocketchat
````
The command starts all dependency containers too.
Optionally, if you want to manage your messages and configuration information, edit the file again to uncomment the volume mounts. Make sure you have a `data` subdirectory to mount and store the data.
Optiionally, if you want a bot, so you don't have to talk to yourself, after you've created an admin user and also a bot user, edit the file `docker-compose.yml` again to change the variables `ROCKETCHAT_USER` and `ROCKETCHAT_PASSWORD` in the hubot section and then start up hubot:
````
docker-compose up -d hubot
````
## Updating the docker image
To update the `rocketchat` docker image to the latest (develop) version, you can use the following commands. Your data should not be affected by this, since it's located in the `mongo` image.
Ansible helps you build a strong foundation for DevOps.
\- Ansible Inc.
Quick Links
-----------
-[Rocket.Chat official Ansible role](https://galaxy.ansible.com/RocketChat/Server/#readme)
-[Ansible official install guide](http://docs.ansible.com/ansible/intro_installation.html)
About
-----
This document will explain, to those unfamiliar with Ansible, how they can get an Ansible environment set-up quickly, with the end goal of deploying Rocket.Chat to a (or multiple) server(s).
It is a quick, dirty HowTo format, not intended to teach you Ansible's full capabilities.
Ansible is an incredible tool, with great documentation, a welcoming comminity, and it's all very easy to pick up - not to mention extremely powerful and suited for just about any situation.
Operational Overview
--------------------
Ansible works on a "push to clients" basis. You have your control node, which pushes all the configuration/ad-hoc tasks out to your systems via SSH, with no client running on the systems you're deploying to! This model means it's very fast, efficient, secure, scalable, and extremely portable.
So, to control remote systems, you only need to install Ansible on your control node - your own desktop would make a great control node to deploy from :)
Getting Ansible
---------------
It's recommended that you check out [Ansible's official documentation on installing](http://docs.ansible.com/ansible/intro_installation.html)(it's really easy!), but here's a quick run down of installation methods:
### Package manager
If you're running a UNIX-like system, like Linux or BSD, Ansible is likely available in your official package repositories.
Use your package manager to see if it's available, and if so, install it!
[Ansible's installation documentation has a section on this](http://docs.ansible.com/ansible/intro_installation.html#latest-release-via-yum) - just scroll down until you see your OS.
### Via Pip
Ansible is written in Python, so, it's only natural that it be available for install via [`pip`](https://pypi.python.org/pypi).
If you have `pip` installed, it's as easy as:
`$ sudo pip install ansible`
If not, check to see if you can install `pip` via your system's package manager (you want the Python 2.7 version!).
Or, if you're on Mac OS X, and you're not using [Homebrew](http://brew.sh) or [pkgsrc](https://github.com/cmacrae/saveosx), you should be able to install `pip` using `easy_install`, like so:
`$ sudo easy_install pip`
then
`$ sudo pip install ansible`
For any other systems, please refer to [Ansible's official documentation on installing](http://docs.ansible.com/ansible/intro_installation.html).
Simple Deployment Environment for Rocket.Chat
---------------------------------------------
So, now you've got Ansible installed, you can get ready to deploy Rocket.Chat!
###Prerequisites
- You must have SSH access to the system you want to deploy to as the `root` user.
- The system you're deploying to must have Python installed (pretty much comes with most operating systems nowadays, easy to install if not).
- The system you're deploying to must run one of the following operating systems:
\- EL 7 (RHEL/CentOS)
\- Debian 8 (Jessie) LTS
\- Ubuntu 14.04 LTS
\- Ubuntu 15.04
Future releases of the [official Rocket.Chat Ansible role](https://galaxy.ansible.com/RocketChat/Server/#readme) will include other Linux distributions/releases and other operating systems. If you'd like to see your OS of choice supported, feel free to [raise an issue](https://github.com/RocketChat/Rocket.Chat.Ansible/issues) to ask if it can be added.
### Inventory set-up
Make a directory somewhere, perhaps in your home directory, or somewhere you keep Git repositories or code. It doesn't really matter what it's called, but for example's sake, we'll call ours `ansible`:
```
~/ $ mkdir ansible
~/ $ cd ansible
~/ansible $
```
Now we're in our `ansible` directory, we're going to make an inventory file.
This is a simple ini formatted file that contains a list of systems that we want to connect to and control using Ansible. It can contain single hosts, group hosts together, groups of groups, set variables on a host or group basis... there are lots of things you can do with the inventory, but that's outside the scope of this document's intended teachings.
Make the inventory file `inventory`, for simplicity's sake:
`~/ansible $ touch inventory`
Now, with your favourite editor, open the file and add the hostname or FQDN of the server(s) you want to deploy Rocket.Chat to, like so:
``` ini
[chat_servers]
chat.my.domain
```
Notice the `[chat_servers]` line? This denotes a group, simply called "chat_servers".
Any hostnames/FQDNs/IP addresses under this will be members of the "chat_servers" group.
If you want to add another server, just drop it in like so:
``` ini
[chat_servers]
chat.my.domain
talk.my.domain
```
We're pretty much done with the inventory, just one last thing whilst we're on the subject: if you are not using SSH keypairs for authenticating your SSH connections to your server(s)... you should be... but if you're not, you can tell Ansible the `root` user's password here in the inventory file.
This is, of course, insecure, and is considered bad practice - so should only be temporary.
Let's set the `root` user's password for the `chat.my.domain` host:
Simple as that! Alright, we're almost ready to deploy Rocket.Chat, just two more things to sort out.
Download the Rocket.Chat Ansible role
-------------------------------------
Ansible has a nice and easy way to share and use other people's roles: [Galaxy](http://galaxy.ansible.com).
You can download roles you want to use using a commandline tool that was installed earlier when you installed Ansible, `ansible-galaxy`.
First off, our roles need somewhere to live, so, let's make a `roles` directory:
`~/ansible $ mkdir roles`
Then, we need to create a `requirements.yml` file that will describe to `ansible-galaxy` how we want to fetch the role. So, create and open the file `roles/requirements.yml` using your favorite editor.
The contents of `requirements.yml` will vary based on which version of Ansible you're running.
Run `ansible --version` to find out.
If you're running Ansible 1.9.4, paste the following into your `requirements.yml`:
``` yaml
-src:RocketChat.Server
version:master
```
If you're running Ansible 2.0, paste the following into your `requirements.yml`:
``` yaml
-src:RocketChat.Server
version:v2.0
```
Next, let's fetch the Rocket.Chat Ansible role using the `ansible-galaxy` command:
This command could be expressed as "Run the `rocket_chat.yml` playbook with the inventory file `inventory`.".
Now we just sit back and watch the magic happen ;)
When it's all done, provided all went well and no parameters were changed, you should be able to visit [https://chat.my.domain](.) and be greeted by a wonderful Rocket.Chat logo and login screen!
There are _lots_ of options you can set with this role, just take a look at the [README](https://github.com/RocketChat/Rocket.Chat.Ansible/blob/master/README.md) to find out more.
`MAKE_CMD=gmake` is important, because meteor requires GNU make to build. The fork we will be building lets us set `MAKE_CMD` so we don't have to do nasty stuff to our BSD make.
## Installing pm2
### Installing pm2
We need pm2 later to deamonize or Rocket.Chat build.
Now, install pm2:
...
...
@@ -40,7 +42,7 @@ $ sudo npm install pm2 -g
$ sudo pm2 startup freebsd
```
## Build meteor
### Building meteor
We need a fork of meteor which allows us to set `MAKE_CMD` as mentioned before:
* Heroku (actually CloudFoundry) uses custom buildpacks to stage applications. The buildpack used by Rocket.Chat can take a very long time to build - since it needs to download Meteor and build the server image every time.
* You *must* set the ROOT_URL environment variable, as shown above, otherwise the server side will crash.
* Note mongolab's free sandbox plan does not support oplog tailing - check other plans if you need oplog.
* If you are scaling to multi-dynos on Heroku, and you have clients/customers still using older browsers that do not support WebSocket, you need to be mindful of sticky session support (BETA) on Heroku - see [sticky sessions on Heroku](https://devcenter.heroku.com/articles/session-affinity).
\ No newline at end of file
* If you are scaling to multi-dynos on Heroku, and you have clients/customers still using older browsers that do not support WebSocket, you need to be mindful of sticky session support (BETA) on Heroku - see [sticky sessions on Heroku](https://devcenter.heroku.com/articles/session-affinity).
While Nitrous.io is not straightly a 'cloud provider' in the conventional sense, depending on the type of account you have - it can certainly used to deploy Rocket.Chat for development or experimentation.
