mattermost / docs

Mattermost documentation

Mattermost Documentation

This repository generates the documentation available at https://docs.mattermost.com/. All documentation is available under the terms of a Creative Commons License.

If you have any questions, create an account on the Mattermost Community server, then join the writing team in the Documentation Working Group channel. We look forward to working with you!

Table of Contents

• Contributing
  • Get started
  • Edit content directly on GitHub
  • Create documentation PRs
  • Use GitHub PR Labels
  • Comment on Pull Requests
  • Review Pull Requests
• Build Mattermost product documentation locally

Contribute to Mattermost product documentation

Get started

You can edit or create Mattermost documentation directly in GitHub, or by downloading the mattermost/docs repository onto your machine and using an IDE such as VS Code. Consult the Mattermost Documentation Style Guide and reStructuredText Markup section for stylistic and technical guidance.

If this is your first time contributing to Mattermost, first read and sign the Mattermost Contributor Agreement, so you can be added to the Mattermost Approved Contributor List.

Edit content directly on GitHub

The quickest way to begin is editing directly on GitHub on your fork of the Mattermost docs repo. Select the Edit icon on the top right corner of the page you want to edit in the Mattermost documentation.

If this is the first time you're contributing, follow these steps:

1. Select Fork in the top-right corner of the GitHub repository page to fork the current repository.
2. Navigate to file you want to edit, then select the Pencil icon (Edit the file) to open the editing interface.

Create Documentation pull requests

1. When you're ready to submit your changes, add a descriptive title and comments to summarize the changes made.
2. Select Create a new branch for this commit and start a pull request.
3. Check the Propose file change button.
4. Scroll down to compare changes with the original document.
5. Select Create pull request.

Use GitHub PR labels

GitHub PR labels are used to track the life cycle and status of a pull request. Using the correct labels helps with managing workflows and ensuring that content is edited, merged and released at the correct time. For example, PRs that include an Editor Review label will be processed by an editor on the writing team to ensure the documentation is correctly formatted at https://docs.mattermost.com/ based on guidelines outlined in the style guide.

Take a look at the Labels page for information about how and when to use which labels.

Comment on pull requests

Once a pull request is submitted, multiple committers may comment on it and provide edits or suggestions which you can commit directly. You can also add line comments. Take a look at Commenting on pull requests for more details.

Review pull requests

Once a pull request has been submitted and the correct label assigned, the review process begins. This includes aligning the content with the Style Guide, validating processes, and tagging any other relevant committers. Read more about the review process and expectations in the Mattermost Developer documentation.

Once the review process is complete, and depending on the type of issue it is (e.g., a typo fix vs. a new feature), the change is either merged into master and pushed immediately or merged into the release branch and pushed in alignment with a future release. The branch is then deleted.

Build locally

If you've downloaded the mattermost/docs repository and are editing Mattermost documentation on your local machine, you can generate the HTML files from markdown in the source directory. You can review your changes before you commit them or create pull requests.

Note: Terminal commands can be executed on Linux, Mac, and Windows (using PowerShell).

Build prerequisites

The following software is required to build the documentation:

• Git [download]
• Python 3.9 or later [download]
• Pipenv [download]

Build instructions

1. Open a terminal window, then clone a forked copy of the documentation repository:

   git clone https://github.com/mattermost/docs.git

2. In the terminal window, navigate into the cloned repository:

   cd docs

3. Install pipenv by using one of the following commands based on your operating system:

   For Mac users where Homebrew is installed:

   brew install pipenv

   For other operating systems:

   pip install --user pipenv

4. Install required Python packages:

   pipenv install --dev

5. Build the documentation set. You have three build commands available at the terminal:

   • Use make html to generate HTML files in the /build directory. Only file you've modified are re-built.
   • Use make clean html to delete all static HTML output in the /build directory and re-build all files. This command is particularly useful when you're making changes to the LHS navigation pane and want to ensure you're not reviewing cached results.
   • Use make livehtml to review a live preview published to http://127.0.0.1:8000 that automatically updates as new changes are saved in your local IDE.

   Windows users will require GNU Make installed for the above commands to work correctly. If GNU Make is not installed, please substitute CMD /C make.bat for make in the above commands to use the Windows command interpreter. For example make html will become CMD /C make.bat html.

   Note: When using the CMD /C make.bat substitution, only a single target may be specified. Instead of running CMD /C make.bat clean html, each target must be run seperately. For example, CMD /C make.bat clean followed by CMD /C make.bat html.

6. When working with static build results, navigate to the build directory:

   cd build

7. Then, preview your changes by opening the build/html/index.html file.

Build errors are written to the build/warnings.log file.

docs's Issues

Changelog not update

in no information about the changes in version 3.6 file

Typing error in mattermost database changes.

At https://docs.mattermost.com/administration/changelog.html#database-changes-from-v3-2-to-v3-3 ,
( Commit
e30c3fa#diff-6d8bc7fdf1108df5a6734816051a32e3R191
)

Users Table

• Added LastActivityAt column.
• Added LastPingAt column.
• Removed ThemeProps column.

But, Actually Users table's column LastActivityAt and LastPingAt removed at v3.3.

( https://github.com/mattermost/platform/blob/c3ae3f20f58b25aa6aba480ddc2239fd09e610cb/store/sql_upgrade.go#L172 )

I try to fix typos, but I found that document database change logs have more errors than I expected.

Can you check document change logs?

[Help Wanted] Add search bar to mobile web experience for docs

Everyone loves the new search experience for docs on desktop:

It's a little more difficult to use on mobile:

typo in screenshot in documentation is no longer present in latest release; screenshot needs updated

This image, which is used in the documentation, contains a typo that is no longer present in the latest release: https://github.com/mattermost/docs/blob/master/source/images/okta_10_mattermost_basics.PNG

The typo is "Pubilc"

The image needs to be updated with a new screenshot of latest release

[Question] Encourage use of virtualenv in the README?

pip install was giving me errors like:

OSError: [Errno 13] Permission denied: '/Library/Python/2.7/site-packages/sphinx'

This requires me to install packages with sudo. I don't program python so might not have configured pip properly. Then I used virtualenv instead which made package installs clean, isolated and without sudo.

This made me wonder if we should encourage contributors to use virtualenv via the README.

Test Issue

Please ignore, test issue

[Help Wanted] Bug: Theme is lost on search results page

Search for term on http://docs.mattermost.com/ and the theme turns from white/grey to blue/black.

Looking for help having the white/grey theme show up on search results page.

Here's a Stack Overflow article with some info:
http://stackoverflow.com/questions/37040952/styling-the-sphinx-theme-search-page

Regular white/grey theme:

Blue/grey theme on search results page (should be white/grey):

Release checklist: Add review of Upgrade Guide and Install Guide each release

Propose adding a checklist item for dev to review the upgrade and install guides and make sure we're not missing any steps, e.g. Dev Meeting review for any missing steps in Upgrade or Install Guides

Example of something we missed: #403

[Help Wanted] Shorten "Edit on GitHub" to "Edit"

The "Edit on GitHub" option seems to be causing layout issues on pages with long titles. Shortening the label probably solves a lot of corner cases.

[Help Wanted] Add Japanese documentation to international documentation page

While docs.mattermost.com does not yet support localization, an international section has been created to support documentation for communities where English language is uncommon.

This ticket is to welcome pull requests for Japanese documentation to be added to this section, based on considerable interest from the Japanese community. For example:

• Qiita articles on Mattermost
• Prototype of localization support for docs.mattermost.com

api oauth docs missing

so we're trying to write a mattermost chat-bot that doesn't have the limitations of the web-hooks (no private channels for example)... We thought this should be easy enough by making a full user-account for the bot and logging it in via the API...

sadly we use our gitlab's oauth and the following section is empty so we can't get it to work:
http://docs.mattermost.com/developer/web-service.html#oauth2

would be cool if someone could take the time to add that section...

by guessing (not sure it's the right track) we already could acquire an access_token from the gitlab oauth:

client_id = 'the one of mattermost in our gitlab'
r = requests.post(
    'https://git.example/oauth/token',
    data={
        "grant_type": "password",
        "username": user,
        "password": pw,
        "client_id": client_id,
    }
)
access_token = r.json()['access_token']

but using it only results in a 401:

ri = requests.get(
    'https://chat.example/api/v1/users/me',
    headers={'Authorization': 'Bearer ' + access_token}
)

ri.status_code, ri.json()
(401,
 {u'detailed_error': u'token=...xxx...',
  u'id': u'api.context.session_expired.app_error',
  u'is_oauth': False,
  u'message': u'Invalid or expired session, please login again.',
  u'request_id': u'...yyy...',
  u'status_code': 401})

http://docs.mattermost.com/administration/command-line-tools.md **is forbidden**

http://docs.mattermost.com/deployment/on-boarding.html this page has "Command Line Tool" links to this page.

Test image

Improving the visual difference between section titles and subtitles

It's not easy to distinguish between section titles and subtitles in the docs at the moment, as the header styles are quite close to each other.

One option is to add a line below the section title so it's easier to distinguish between the two

Opening a GitHub issue to start discussion -- came up during a PM group review on docs earlier today.

Document how to create a clickable button in markdown

Probably create or find a better image, but basically here's the markdown to create a button:

[![button](http://www.presentationpro.com/images/product/medium/slide/PPP_CGENE_LT3_Presentation-PowerPoint-Slide-Graphic_Push_Button_Up.jpg)](https://mattermost.com)

Upgrade Guide should mention that you may need to set Mattermost account as directory owner again after upgrading

I upgraded to the Enterprise Edition from the Team Edition, and then ran into an issue when uploading the Identity Provider Public Certificate for SAML: https://docs.mattermost.com/deployment/sso-saml-okta.html

It turns out I had to run the following commands after the upgrade, to be able to upload the certificate:

sudo chown -R mattermost:mattermost /opt/mattermost
sudo chmod -R g+w /opt/mattermost

These are mentioned in the Install documentation, but should probably be mentioned in the Upgrade guide: https://docs.mattermost.com/administration/upgrade.html

[Help Wanted] Enable headings in Left Sidebar to collapse when clicked

Would appreciate help from anyone who knows how to get the headings, e.g. "MESSAGING", "GETTING STARTED", etc. to collapse the links below them when clicked, and expand them when clicked again.

It's probably a setting in Sphinx, we just need help understanding which setting.

404 link on https://docs.mattermost.com/install/prod-docker.html

"Start, stop and remove containers using management instructions." gets a 404 from github.

I reckon this is because the tag name in the target repo has changed.

I'll do a PR to fix it.

Render markdown in search results

Currently markdown appears but does not render in search results on docs.mattermost.com. Ideally markdown would fully render in the search results.

Update upgrade guide for TLS setup on Mattermost server

If TLS is setup on Mattermost server (i.e. no NGINX) there needs to be an extra step during upgrade: https://docs.mattermost.com/install/setup-tls.html

We should either find a way to automate this step or note it in the upgrade guide.

Match docs repo with Mattermost server version

Repo is on "3.0" but server is on "3.3". Creates confusing search results.

[Help Wanted] Create install guide variant with MySQL commands for Ubuntu 16.04, RHEL6 and RHEL7

While MySQL is more popular than Postgres, the Mattermost install guides default to Postgres.

This ticket is to create a variant of the Ubuntu, RHEL6 and RHEL7 install guides that offer step-by-step instructions for MySQL.

Please post-fix the names of the new files with mysql, so for prod-rhel-6 please call it prod-rhel-6-mysql.

[Help Wanted] Set up a system for creating permanent links

With the current, if a doc is renamed or moved, its URL changes.

This sometimes causes issues if the help documentation was linked to in the product, because older versions may contain broken documentation links.

To make it easier, we'd like to add a system for creating permanent links that redirect to the correct docs. We can then keep the permanent link in the product, and just update which document the permanent link points to.

Ubuntu 16.04 instructions needed

I have gone through the steps outlined in section Set up Mattermost Server.

When I get to step 9 and run the command sudo start mattermost, it fails with error message:
[sudo] password for ubuntu:
start: Unable to connect to Upstart: Failed to connect to socket /com/ubuntu/upstart: Connection refused

The machine is running Ubuntu 16.04.1 x64 (a DigitalOcean droplet).

How to start Mattermost automatically ?

Hi everyone !

Can we start mattermost on startup ?

Now we have to pass root and run ./mattermost/bin/platform

Can we add a mattermost service module to start automatically ?

Thanks.

[Help Wanted] Change "View page source" link to "Edit" link to GitHub page

Would appreciate help from anyone who can make a PR to change the "View page source" link to an "Edit" link to GitHub page to make it easier for community members to contribute changes.

Inconsistent Nginx setup recommendations

In the various Linux install docs, there are three different recommendations for the contents of /etc/nginx/conf.d/mattermost.conf

These are the files that contain Nginx setup instructions:

ee-prod-rhel-6.rst
ee-prod-rhel-7.rst
ee-prod-ubuntu.rst
prod-debian.rst
prod-rhel-6.rst
prod-rhel-7.rst
prod-ubuntu-16.04.rst
prod-ubuntu-1404.rst

Is there a best one that can be used consistently? This is what's there now:

For ee-prod-ubuntu.rst, prod-debian.rst, prod-rhel-6.rst, and prod-rhel-7.rst:

  server {
	 listen         80;
	 server_name    mattermost.example.com;
	 return         301 https://$server_name$request_uri;
	}

	server {
	 listen 443 ssl;
	 server_name mattermost.example.com;

	 ssl on;
	 ssl_certificate /etc/letsencrypt/live/yourdomainname/fullchain.pem;
	 ssl_certificate_key /etc/letsencrypt/live/yourdomainname/privkey.pem;
	 ssl_session_timeout 5m;
	 ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
	 ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';
	 ssl_prefer_server_ciphers on;
	 ssl_session_cache shared:SSL:10m;

	 location / {
		gzip off;
		proxy_set_header X-Forwarded-Ssl on;
		client_max_body_size 50M;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection "upgrade";
		proxy_set_header Host $http_host;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Forwarded-Proto $scheme;
		proxy_set_header X-Frame-Options SAMEORIGIN;
		proxy_pass http://10.10.10.2:8065;
	 }
	}

For ee-prod-rhel-6.rst and ee-prod-rhel-7.rst:

  server {
	 listen         80;
	 server_name    mattermost.example.com;
  }

  server {
	 listen 443 ssl;
	 server_name mattermost.example.com;

	 ssl on;
	 ssl_certificate /etc/letsencrypt/live/yourdomainname/fullchain.pem;
	 ssl_certificate_key /etc/letsencrypt/live/yourdomainname/privkey.pem;
	 ssl_session_timeout 5m;
	 ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
	 ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';
	 ssl_prefer_server_ciphers on;
	 ssl_session_cache shared:SSL:10m;

	 location / {
		gzip off;
		proxy_set_header X-Forwarded-Ssl on;
		client_max_body_size 50M;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection "upgrade";
		proxy_set_header Host $http_host;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Forwarded-Proto $scheme;
		proxy_set_header X-Frame-Options SAMEORIGIN;
		proxy_pass http://10.10.10.2:8065;
	 }
  }

For prod-ubuntu-16.04.rst and prod-ubuntu-1404.rst:

        upstream backend {
            server 10.10.10.2:8065;
        }

        proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off;

        server {
            listen 80;
            server_name    mattermost.example.com;

            location /api/v3/users/websocket {
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "upgrade";
                client_max_body_size 50M;
                proxy_set_header Host $http_host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_set_header X-Frame-Options SAMEORIGIN;
                proxy_buffers 256 16k;
                proxy_buffer_size 16k;
                proxy_read_timeout 600s;
                proxy_pass http://backend;
            }

            location / {
                client_max_body_size 50M;
                proxy_set_header Connection "";
                proxy_set_header Host $http_host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_set_header X-Frame-Options SAMEORIGIN;
                proxy_buffers 256 16k;
                proxy_buffer_size 16k;
                proxy_read_timeout 600s;
                proxy_cache mattermost_cache;
                proxy_cache_revalidate on;
                proxy_cache_min_uses 2;
                proxy_cache_use_stale timeout;
                proxy_cache_lock on;
                proxy_pass http://backend;
            }
        }

[Help Wanted] Documenting APIs for Mattermost 3.5

We're looking for help with documenting the Mattermost APIs available in 3.5!

At Mattermost we use the OpenAPI specification for documenting our APIs.

If you're interested in helping out, please head over to the issues page on our mattermost/mattermost-api-reference repository and feel to grab any issue labelled Help Wanted.

Any documentation you add will be hosted on our official API reference at https://api.mattermost.com.

Add "PDF" to Options menu to export pages to PDF

• This would be adding the ability to export documentation pages in .rst to PDF, see previous discussion: #85 (comment)
• It would be nice if there was a way to export from .md files as well, but we can also do the work to convert those to .rst. The .rst format has more formatting options than markdown, and there are tools to help with conversion so it's probably good to do. The downside is that markdown is more popular.

Developer Setup omits installation of VirtualBox

On the Developer Setup page, under Mac OS X setup, step 1.2 "Start a new docker host" fails as follows:

$ docker-machine create -d virtualbox dev
Running pre-create checks...
Error with pre-create check: "VBoxManage not found. Make sure VirtualBox is installed and VBoxManage is in the path"

Perhaps there should be a step before this to describe a preferred way to install VirtualBox?

AWS Docker Setup Guide Issue

The AWS setup guide at docs/source/install/docker-ebs.rst specifies to select a t2.small or larger instance, and that the "options on the Additional Resources page may be left at default unless you wish to change them." However, the t2.* instances require a VPC environment to be configured as well, otherwise the instance will fail when it is created.

I don't know if the best solution is to recommend an m3 instance, or provide details on configuring the VPC for the setup guide.

Creating Auto Scaling group named: [group] failed Reason: The specified instance type can only be used in a VPC. A subnet ID or network interface ID is required to carry out the request. Launching EC2 instance failed.

Changing border around images to 1px and grey, similar to image border in product?

The borders in docs are BLACK and HEAVY around images. They seem out-of-place.

Propose switching to a 1px grey border similar to image borders in the product on default theme.

[Help Wanted] Figure out where to add Community Content Guidelines

This was removed from a PR to Community Guidelines page. It's looking for a new home. Any thoughts?

Community Content Guidelines 
==============================================================

Content from community in GitHub, Forums, Feature Ideas, Community Mattermost site or any other community content site managed by Mattermost should follow Mattermost guidelines: 

Content that is deemed to be controversial, offensive, potentially defamatory or infringing content from material distributed, broadcast, or posted on websites will be edited or removed. 

We ask the community's help in reporting any such content to [email protected]   

[Help Wanted] How to turn on Options for Sphinx site

Can anyone help us turn on the "Options" for exporting to PDF and EPUB?

Not sure if this requires custom work, help would be appreciated from anyone might be familiar with Sphinx

Example below of what we're looking for from MongoDB documentation as an example.

Help Wanted: Chapter on Windows setup with IIS

Thanks to Golang, we have a Windows build included in each release of the Mattermost server, but we don't have a chapter in our install guide to walk people through how to set it up properly.

This ticket is to copy an paste one of our Linux install guides to create the Windows server setup chapter with IIS.

Once the chapter is ready, it could be announced to the people who have voted for this feature previously to help test and provide feedback before we announce Windows support as official (or possibly beta, depending on how the testing goes).

Default NGINX SSL setup results in weak Diffie-Hellman key exchange parameters

If you follow the instructions in the doc https://docs.mattermost.com/install/prod-ubuntu-16.04.html#set-up-nginx-with-ssl-recommended, you end up with an NGINX config that supports weak Diffie-Hellman (DH) key exchange parameters. This prevents an A rating from the site that the docs recommend for testing the SSL config, Qualys SSL Labs.

The instructions should include how to configure a Mattermost system to get an A rating.

[Help Wanted] Change Nginx to NGINX

In all its documentation NGINX refers to itself in all capitals: https://www.nginx.com/resources/wiki/

[Help Wanted] Limit sidebar to show a maximum of three levels of nesting.

Observed: The sidebar will expand to as many levels of heading as are in the document. See screenshot #1.

Expected: The sidebar is limited to expanding to three nested levels of headings. For the above example, the maximum expansion of the sidebar would be:

[Help Wanted] Update documentation guidelines

Our existing guidelines are a bit out of date, would appreciate a PR to replace them. We can use the PR to discuss

[Help Wanted] CSS to fix line wraps in titles for left-hand sidebar

After the re-org PR goes in, propose having someone fix CSS for line wraps in left-hand sidebar.

Right now, formatting is all broken:

Update style guides documentation

1. Add user account and parameter formatting to documentation style guides

From discussion with @JeffSchering #742 (comment)

[Help Wanted] Error when searching for "Reply" in docs.mattermost.com

Repro:

1. Search for "Reply" on docs.mattermost.com

Observed:

1. System freezes and JS error seen in console. Does not happen when you search for "Fish"

[Help Wanted] Bug: Linking to a section heading of a document causes the scroll to offset by the width of the Mattermost header bar

Repro:

1. Click a link to a specific section header in a document (for example, https://docs.mattermost.com/deployment/cluster.html#file-storage-configuration)

Observed: The section header is hidden behind the "Mattermost" header bar because the scroll is offset. This only seems to happen the first time the link is visited.

Expected: Page is scrolled so linked section starts just below the "Mattermost" header bar

See screenshot:

[Help Wanted] Reorganize and correct Desktop App info table

https://docs.mattermost.com/help/apps/desktop-guide.html#id2

Propose:

1. Name the columns Windows, Mac and Linux (rather than having "OS X", which is less obvious)
2. Re-order rows so we have all the Yes, Yes, Yes at the top, then Yes, X, X, then [BLANK], YES, X. so it's easier to see what's in Windows (most popular),
3. Re-order the settings in the section below so it matches the table.
4. Update table to match the description below, example: In the description Start App on Logon is only available on Windows and Linux, but the table shows it's available on Mac, this doesn't appear to be correct.

Here is Setting Page on Mac:

[Help Wanted] Momentum scroll on mobile devices

Navigate to docs.mattermost.com on a mobile device and notice that the website scroll is fixed to your finger movement.

Expected: momentum scroll observed on most other websites.

[Help Wanted] Help fix LEFT SIDE menu button on docs.mattermost.com on mobile web

Repros:

• Go to docs.mattermost.com on mobile web and click the LEFT SIDE menu button

Observed:

• Blank sidebar appears :

Expected:

• LEFT SIDE menu button should either not appear on docs.mattermost.com on mobile web, or it should redirect to https://docs.mattermost.com/overview/index.html

[Help Wanted] Review Docker setup for Windows

This PR has been waiting for a review for a while, would love help from someone who can test and verify the setup: https://github.com/mattermost/docs/pull/439/files

[Help wanted] Fix search for "Upgrade"

Search for "Upgrade" and upgrade page doesn't appear. Need to find out why, and later write out some criteria so it is easier to find regressions in search

Document how to use and configure https://hub.docker.com/r/mattermost/webrtc/

Document how to use and configure https://hub.docker.com/r/mattermost/webrtc/

More information here: http://forum.mattermost.org/t/where-is-the-mattermost-webrtc-documentation/2508

Cannot access to "Creating Teams" page

Hi,

Thank for your work !

I have a problem with docs, I cannot access to "Creating Teams" page, return me 403 HTTP code :(
See screenshot :

Thank for your help.