Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve Readme #262

Merged
merged 2 commits into from
Mar 24, 2020
Merged

Improve Readme #262

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a6601e1
Improve Readme
angeliski Mar 24, 2020
af6b419
Fix minor typos
angeliski Mar 24, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 89 additions & 68 deletions README.md
View file
Open in desktop
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**
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's "the", an example: https://www.youtube.com/watch?v=QdurBIvrIWg

And the ideal even if it is two "#" because the main topic is the first line


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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here you don't give the title space, in the previous title you give it. Use the vscode markdown plugin and have the file formatted.

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
Open in desktop
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could put a badge at the beginning to indicate Slack, many people will not even get here at the end, and it also avoids an extra topic. What do you think?


## 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)