Skip to content

Commit

Permalink
Merge pull request #262 from ResultadosDigitais/docs-readme-rewrited
Browse files Browse the repository at this point in the history 
Improve Readme
  • Loading branch information
@angeliski
angeliski authored Mar 24, 2020
2 parents d02db73 + af6b419 commit b5d3b08
Show file tree
Hide file tree
Showing 2 changed files with 127 additions and 68 deletions.
157 changes: 89 additions & 68 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<a href="https://circleci.com/gh/ResultadosDigitais/matrix"><img alt="CircleCI Status" src="https://img.shields.io/circleci/project/github/babel/babel/master.svg?label=CircleCI&maxAge=43200"></a>
</p>

## Welcome to the **#matrix**
# Welcome to **#matrix**

The objective of **#matrix** project is to offer a virtual environment office, as nice as physical offices. When we are working in a physical office is very common entering in discussion threads in many different environments, for example: on coffee, on lunch and others.

Expand All @@ -17,82 +17,45 @@ When we are working remotely there are no conversations like in a physical offic

![Matrix Home Screenshot](docs/img/matrix-morpheus.png)

## Versions

| Version | Name | Description | Docs |
| --- | --- | --- | --- |
| 2.0.0 | Seraph | New authentication | [Migration guide to 2.0.0](/docs/MIGRATION-TO-V2.md) |
| 1.1.0 | Morpheus | New layout | [Pull request](https://github.com/ResultadosDigitais/matrix/pull/174) |
| 1.0.0 | Neo | The one project | - |


## Authentication

The login is so simple. You only need to configure the Google API credentials following [this step by step](/docs/GOOGLE-CREDENTIAL-STEP-BY-STEP.md) .

| Login | Login in Dark Mode |
| :-------------------------------------------------------------------: | :-------------------------------------------------------------------------------------: |
| <img src="docs/img/matrix-login.png" title="Login page" width="100%"> | <img src="docs/img/matrix-dark-login.png" title="Login page in Dark Mode" width="100%"> |

## The rooms Inside of #matrix
## Table of Contents
1. [Understanding #matrix](#Understanding-#matrix)
1. [Rooms](#Rooms)
2. [Availability And Meetings](#Availability-And-Meetings)
2. [Installation](#Installation)
1. [Environment Variables](#Environment-Variables)
2. [Authentication](#Authentication)
3. [Docker Compose](#Docker-Compose)
4. [On GCP](#On-GCP)
5. [On Heroku](#On-Heroku)
6. [Production concerns](#Production-concerns)
3. [Versions](#Versions)
4. [Contributing](#Contributing)
5. [Frequently Asked Questions](#Frequently-Asked-Questions)
6. [Get in Touch](#Get-in-Touch)
7. [License](#License)

## Understanding #matrix
### Rooms
The inside of **#matrix** there are some rooms. In this rooms is possible to see others colleagues and if they are talking or in a meeting in the avatar will appear a head set icon. (eg. In the image the guys in the Platform-Email room are in a meeting)

| Office Page | With Sidebar |
| :--------------------------------------------------------------------: | :----------------------------------------------------------------------------------: |
| <img src="docs/img/matrix-rooms.png" title="Office page" width="100%"> | <img src="docs/img/matrix-online.png" title="Office page with Sidebar" width="100%"> |

## The meeting room

You can only enter in a room to show for the other that you are available there through the `ENTER ROOM` button or enter in a meeting through the button `ENTER MEETING`.
### Availability And Meetings
**#matrix** is a virtual environment office, so you can show you are available for the other on enter in a room through the `ENTER ROOM` button. This is like "Hey, I am here in the office".
Or you can enter in a meeting through the button `ENTER MEETING`.

The embeded meet is provided by [meet.jit.si](https://meet.jit.si) service and this service is maintained by the [Jitsi team](https://jitsi.org/the-community/#meet-our-team)
at [8x8](https://8x8.com). Access the [jitsi GitHub](https://github.com/jitsi/jitsi-meet#security) and learn more about this amazing video bridge service.
at [8x8](https://8x8.com). Access the [jitsi GitHub](https://github.com/jitsi/jitsi-meet#security) and learn more about this amazing video bridge service. You can change that using [external meet option](#External-Meet) in any room.


| Meeting Room | With Sidebar |
| :------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------: |
| <img src="docs/img/matrix-meet-room.png" title="Office page" width="100%"> | <img src="docs/img/matrix-meet-room-sidebar.png" title="Office page with Sidebar" width="100%"> |

## Getting Started

If you want run the **#matrix**, you need follow steps:

1. Clone this repository `git clone git@github.com:ResultadosDigitais/matrix.git`

2. We are using Google to authorizations, you need create a credential [here](/docs/GOOGLE-CREDENTIAL-STEP-BY-STEP.md) you can follow step by step

3. duplicate file `variables.example.env` and rename to `variables.env`, after that set your environment variables;

4. Run application with docker compose:

$ docker-compose up

5. Open your browser and access:

http://localhost:8080/

6. When you finish, you can run:

$ docker-compose down

## On GCP

If you prefer, you can run **#matrix** on GCP:

[![Run on Google Cloud](https://deploy.cloud.run/button.svg)](https://deploy.cloud.run?git_repo=https://github.com/ResultadosDigitais/matrix&revision=gcp-deploy-button)


## On Heroku

If you prefer, you can run **#matrix** in Heroku:

[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/ResultadosDigitais/matrix)


## Environment Variables

## Installation
### Environment Variables
The **#matrix** project has some environment variables that important to define.

- We are using Google to authorizations, you need create a credential [here](https://developers.google.com/identity/sign-in/web/sign-in) and before define this variables:
Expand Down Expand Up @@ -139,32 +102,90 @@ The **#matrix** project has some environment variables that important to define.
]


### External Meet

The default video conferencing in meetings is [Jitsi](https://jitsi.org/jitsi-meet/), but you can change that in any room, using [Meet](https://meet.google.com/) or [Zoom](https://zoom.us/). For that, you just need provide the parameter `externalMeetUrl` in your room config:
#### External Meet
The embeded meet is provided by [meet.jit.si](https://meet.jit.si) service, but you can change that in any room, using serices like [Meet](https://meet.google.com/) or [Zoom](https://zoom.us/). For that, you just need provide the parameter `externalMeetUrl` in your room config:

ROOMS_DATA=[
{
"id":"${UUID}",
"name":"Meeting External",
"externalMeetUrl": "https://external-url-room/key-room"
"externalMeetUrl": "https://external-url-room/key-room"
}
]
### Authentication

The login is so simple. You only need to configure the Google API credentials following [this step by step](/docs/GOOGLE-CREDENTIAL-STEP-BY-STEP.md) .

## Running in Production
| Login | Login in Dark Mode |
| :-------------------------------------------------------------------: | :-------------------------------------------------------------------------------------: |
| <img src="docs/img/matrix-login.png" title="Login page" width="100%"> | <img src="docs/img/matrix-dark-login.png" title="Login page in Dark Mode" width="100%"> |
### Docker Compose

If you want run the **#matrix**, you need [docker-compose](https://docs.docker.com/compose/) and follow steps:

1. Clone this repository `git clone git@github.com:ResultadosDigitais/matrix.git`

2. We are using Google to authorizations, you need create a credential [here](/docs/GOOGLE-CREDENTIAL-STEP-BY-STEP.md) you can follow step by step

3. duplicate file `variables.example.env` and rename to `variables.env`, after that set your environment variables;

4. Run application with docker compose:

$ docker-compose up

5. Open your browser and access:

http://localhost:8080/

6. When you finish, you can run:

$ docker-compose down

### On GCP

If you prefer, you can run **#matrix** on GCP:

[![Run on Google Cloud](https://deploy.cloud.run/button.svg)](https://deploy.cloud.run?git_repo=https://github.com/ResultadosDigitais/matrix&revision=gcp-deploy-button)

### On Heroku

If you prefer, you can run **#matrix** in Heroku:

[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/ResultadosDigitais/matrix)

### Production concerns

If you will run in production we strongly recommend you close your environment using an internal VPN. In this solution everybody with the link and a valid google credential can enter your virtual office. Because this is important for you to maintain your environment closed. Or you can define a variable `WHITELIST_DOMAINS` to limit only authorized users to enter in the **#matrix**. You have to choose a strong key to the `COOKIE_SESSION_SECRET` and have to put in `GOOGLE_CALLBACK_URL` your production domain.

WHITELIST_DOMAINS=["@domain1.com","@domain2.com"]

## Versions

| Version | Name | Description | Docs |
| --- | --- | --- | --- |
| 2.0.0 | Seraph | New authentication | [Migration guide to 2.0.0](/docs/MIGRATION-TO-V2.md) |
| 1.1.0 | Morpheus | New layout | [Pull request](https://github.com/ResultadosDigitais/matrix/pull/174) |
| 1.0.0 | Neo | The one project | - |


## Contributing

We encourage you to contribute to The **#matrix**!

Everyone interacting in **#matrix** codebase, issue trackers, chat rooms, and mailing lists is expected to follow [code of conduct](docs/CODE_OF_CONDUCT.md).

## Frequently Asked Questions

Some questions come up over and over again. Check here first:
[FAQ](docs/faq.md)

## Get in Touch
There are several ways to get in touch with us:

* Open an issue at: https://github.com/ResultadosDigitais/matrix/issues
* See questions on Stackoverflow using tags: https://stackoverflow.com/questions/tagged/hash-matrix
* Chat with us on: http://hash-matrix.slack.com/ ([Invite here](https://join.slack.com/t/hash-matrix/shared_invite/zt-cwglw6te-kMlJiimq7qn4WeSTiv91og))

## License

Expand Down
38 changes: 38 additions & 0 deletions docs/faq.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# FAQs
Here is a list of some frequently asked questions about **#matrix**.

- [How do I ask for help?](#How-do-I-ask-for-help?)
- [What if I find a bug?](#What-if-I-find-a-bug?)
- [Can I request a new feature?](#Can-I-request-a-new-feature?)
- [Does #matrix do X?](#Does-#matrix-do-X?)
- [How do I integrate #matrix and our single-sign on (SSO) solution?](#How-do-I-integrate-#matrix-and-our-single-sign-on-(SSO)-solution?)


## How do I ask for help?
You can use Stackoverflow or Slack for that. Please, do not open a support ticket in any [Resultados Digitais channel](https://resultadosdigitais.com.br/).

* https://stackoverflow.com/questions/tagged/hash-matrix
* http://hash-matrix.slack.com/ ([Invite here](https://join.slack.com/t/hash-matrix/shared_invite/zt-cwglw6te-kMlJiimq7qn4WeSTiv91og))

## What if I find a bug?
If you come across something that looks like a bug, start by searching our [Github issues](https://github.com/ResultadosDigitais/matrix/issues) to see if it has already been reported. If it has, please let us know you're experiencing the same issue by reacting with a thumbs up emoji or adding a comment providing additional information.

If the bug has not yet been reported, go ahead and [open a bug report](https://github.com/ResultadosDigitais/matrix/issues/new/choose). We suggest collecting the following information to help us reproduce the issue:

1. Server logs
2. Javascript console logs
3. Can it be reproduced on the sample dataset? (Rooms / Enviroments config)
4. Your #matrix version
5. Where #matrix is running (Docker image, AWS Elastic Beanstalk, Heroku, Linux/Ubuntu, etc)
6. What browser version
7. Screenshots (if relevant)

## Can I request a new feature?
Absolutely! New features can be added as issues in our [Github repo](ttps://github.com/ResultadosDigitais/matrix/issues). Before filing, take a minute to search and see if your feature has already been requested. If it has, it’s better to leave a thumbs up reaction on the existing issue than to file a new one. We use the thumbs up to measure how interested our community is in new features, so it’s better to have all of the thumbs ups captured on one issue.


## Does #matrix do X?
If you’re not sure if #matrix has the capability you’re looking for, we would recommend asking in [Slack](http://hash-matrix.slack.com/). If it’s something we don’t do, our friendly community may be able to point you towards a workaround, or the Github issue where the feature has been requested.

## How do I integrate #matrix and our single-sign on (SSO) solution?
Nowadays #matrix only support Google Auth, but we are working in provide other solutions (see [#229](https://github.com/ResultadosDigitais/matrix/issues/229) for more details)

0 comments on commit b5d3b08

Please sign in to comment.