diff options
Diffstat (limited to 'doc/install')
| -rw-r--r-- | doc/install/aws-ebs-setup.md | 27 | ||||
| -rw-r--r-- | doc/install/dev-setup.md | 82 | ||||
| -rw-r--r-- | doc/install/requirements.md | 70 | ||||
| -rw-r--r-- | doc/install/single-container-install.md | 120 |
4 files changed, 299 insertions, 0 deletions
diff --git a/doc/install/aws-ebs-setup.md b/doc/install/aws-ebs-setup.md new file mode 100644 index 000000000..452cfcb4f --- /dev/null +++ b/doc/install/aws-ebs-setup.md @@ -0,0 +1,27 @@ + +## AWS Elastic Beanstalk Setup (Docker) + +1. Create a new Elastic Beanstalk Docker application using the [Dockerrun.aws.zip](docker/0.6/Dockerrun.aws//Dockerrun.aws.zip) file provided. + 1. From the AWS console select Elastic Beanstalk. + 2. Select "Create New Application" from the top right. + 3. Name the application and press next. + 4. Select "Create a web server" environment. + 5. If asked, select create an IAM role and instance profile and press next. + 6. For predefined configuration select under Generic: Docker. For environment type select single instance. + 7. For application source, select upload your own and upload Dockerrun.aws.zip from [Dockerrun.aws.zip](docker/0.6/Dockerrun.aws//Dockerrun.aws.zip). Everything else may be left at default. + 8. Select an environment name, this is how you will refer to your environment. Make sure the URL is available then press next. + 9. The options on the additional resources page may be left at default unless you wish to change them. Press Next. + 10. On the configuration details place. Select an instance type of t2.small or larger. + 11. You can set the configuration details as you please but they may be left at their defaults. When you are done press next. + 12. Environment tags my be left blank. Press next. + 13. You will be asked to review your information. Press Launch. + +4. Try it out! + 14. Wait for beanstalk to update the environment. + 15. Try it out by entering the domain of the form \*.elasticbeanstalk.com found at the top of the dashboard into your browser. You can also map your own domain if you wish. + + + ### (Recommended) Enable Email + The default single-container Docker instance for Mattermost is designed for product evaluation, and sets `ByPassEmail=true` so the product can run without enabling email, when doing so maybe difficult. + + To see the product's full functionality, [enabling SMTP email is recommended](doc/config/smtp-email-setup.md). diff --git a/doc/install/dev-setup.md b/doc/install/dev-setup.md new file mode 100644 index 000000000..a088bbbc2 --- /dev/null +++ b/doc/install/dev-setup.md @@ -0,0 +1,82 @@ +Developer Machine Setup +----------------------------- + +### Mac OS X ### + +1. Download and set up Boot2Docker + 1. Follow the instructions at http://docs.docker.com/installation/mac/ + 1. Use the Boot2Docker command-line utility + 2. If you do command-line setup use: `boot2docker init eval “$(boot2docker shellinit)”` + 2. Get your Docker IP address with `boot2docker ip` + 3. Add a line to your /etc/hosts that goes `<Docker IP> dockerhost` + 4. Run `boot2docker shellinit` and copy the export statements to your ~/.bash_profile +2. Download Go from http://golang.org/dl/ +3. Set up your Go workspace + 1. `mkdir ~/go` + 2. Add the following to your ~/.bash_profile + `export GOPATH=$HOME/go` + `export PATH=$PATH:$GOPATH/bin` + 3. Reload your bash profile + `source ~/.bash_profile` +4. Install Node.js using Homebrew + 1. Download Homebrew from http://brew.sh/ + 2. `brew install node` +5. Install Compass + 1. Make sure you have the latest verison of Ruby + 2. `gem install compass` +6. Download Mattermost + `cd ~/go` + `mkdir -p src/github.com/mattermost` + `cd src/github.com/mattermost` + `git clone github.com/mattermost/platform.git` + `cd platform` +7. Run unit tests on Mattermost using `make test` to make sure the installation was successful +8. If tests passed, you can now run Mattermost using `make run` + +Any issues? Please let us know on our forums at: http://forum.mattermost.org + +### Ubuntu ### + +1. Download Docker + 1. Follow the instructions at https://docs.docker.com/installation/ubuntulinux/ or use the summary below: + `sudo apt-get update` + `sudo apt-get install wget` + `wget -qO- https://get.docker.com/ | sh` + `sudo usermod -aG docker <username>` + `sudo service docker start` + `newgrp docker` +2. Set up your dockerhost address + 1. Edit your /etc/hosts file to include the following line + `127.0.0.1 dockerhost` +3. Install build essentials + 1. `apt-get install build-essential` +4. Download Go from http://golang.org/dl/ +5. Set up your Go workspace and add Go to the PATH + 1. `mkdir ~/go` + 2. Add the following to your ~/.bashrc + `export GOPATH=$HOME/go` + `export GOROOT=/usr/local/go` + `export PATH=$PATH:$GOROOT/bin` + 3. Reload your bashrc + `source ~/.bashrc` +6. Install Node.js + 1. Download the newest version of the Node.js sources from https://nodejs.org/download/ + 2. Extract the contents of the package and cd into the extracted files + 3. Compile and install Node.js + `./configure` + `make` + `make install` +7. Install Ruby and Compass + `apt-get install ruby` + `apt-get install ruby-dev` + `gem install compass` +8. Download Mattermost + `cd ~/go` + `mkdir -p src/github.com/mattermost` + `cd src/github.com/mattermost` + `git clone github.com/mattermost/platform.git` + `cd platform` +9. Run unit tests on Mattermost using `make test` to make sure the installation was successful +10. If tests passed, you can now run Mattermost using `make run` + +Any issues? Please let us know on our forums at: http://forum.mattermost.org diff --git a/doc/install/requirements.md b/doc/install/requirements.md new file mode 100644 index 000000000..fa54e81ef --- /dev/null +++ b/doc/install/requirements.md @@ -0,0 +1,70 @@ +## Software Requirements + +### Web Client + +Supported Operating Systems and Browsers for the Mattermost Web Client include: + +- PC: Windows 7, Windows 8 (Chrome 43+, Firefox 38+, Internet Explorer 10+) +- Mac: OS 10 (Safari 7, Chrome 43+) +- Linux: Arch 4.0.0 (Chrome 43+) +- iPhone 4s and higher (Safari on iOS 8.3+, Chrome 43+) +- Android 5 and higher (Chrome 43+) + +### Server + +Supported Operating Systems for the Mattermost Server include: + +- Ubuntu +- Debian +- CentOS +- RedHat Enterprise Linux +- Oracle Linux + +The Mattermost roadmap does not currently include production support for Fedora, FreeBSD or Arch Linux. + +## Hardware Requirements + +Mattermost offers both real-time communication and file sharing. CPU and Memory requirements are typically driven by the number of concurrent users using real-time messaging. Storage requirements are typically driven by number and size of files shared. + +The below guidelines offer estimates based on real world usage of Mattermost across industries. + +### CPU + +- 2 cores is the recommended number of cores and supports up to 250 users +- 4 cores supports up to 1,000 users +- 8 cores supports up to 2,500 users +- 16 cores supports up to 5,000 users +- 32 cores supports up to 10,000 users +- 64 cores supports up to 20,000 users + +### Memory + +- 2GB RAM is the recommended memory size and supports up to 50 users +- 4GB RAM supports up to 500 users +- 8GB RAM supports up to 1,000 users +- 16GB RAM supports up to 2,000 users +- 32GB RAM supports up to 4,000 users +- 64GB RAM supports up to 8,000 users +- 128GB RAM supports up to 16,000 users + +### Storage + +To estimate initial storage requirements begin with a Mattermost server approximately 600 MB to 800 MB in size including operating system and database, then add the multiplied product of: + +- Estimated storage per user per month (see below), multipled by 12 months in a year +- Estimated mean average number of users in a year +- A 1-2x safety factor + +**Estimated storage per user per month** + +File usage per user varies significantly across industries. The below benchmarks are recommended: + +- **Low usage teams** (1-5 MB/user/month) - Primarily use text-messages and links to communicate. Examples would include software development teams that heavily use web-based document creation and management tools, and therefore rarely upload files to the server. + +- **Medium usage teams** (5-25 MB/user/month) - Use a mix of text-messages and shared documents and images to communicate. Examples might include business teams that may commonly drag and drop screenshots, PDFs and Microsoft Office documents into Mattermost for sharing and review. + +- **High usage teams** - (25-100 MB/user/month) - Heaviest utlization comes from teams uploading a high number of large files into Mattermost on a regular basis. Examples include creative teams sharing and storing artwork and media with tags and commentary in a pipeline production process. + +*Example:* A 30 person team with medium usage (5-25 MB/user/month) with a safety factor of 2x would require between 300 MB (30 users * 5 MB * 2x safety factor) and 1500 MB (30 users * 25 MB * 2x safety factor) of free space in the next year. + +It's recommended to review storage utilization at least quarterly to ensure adequate free space is available. diff --git a/doc/install/single-container-install.md b/doc/install/single-container-install.md new file mode 100644 index 000000000..3e307ca74 --- /dev/null +++ b/doc/install/single-container-install.md @@ -0,0 +1,120 @@ +# Single Container Installation and Upgrade + +The following install instructions are for single-container installs of Mattermost using Docker for exploring product functionality and upgrading to newer versions. + +Local Machine Setup (Docker) +----------------------------- + +### Mac OSX ### + +1. Install Boot2Docker using instructions at: http://docs.docker.com/installation/mac/ + 1. Start Boot2Docker from the command line and run: `boot2docker init eval “$(boot2docker shellinit)”` +2. Get your Docker IP address with: `boot2docker ip` +3. Use `sudo nano /etc/hosts` to add `<Docker IP> dockerhost` to your /etc/hosts file +4. Run: `boot2docker shellinit` and copy the export statements to your ~/.bash\_profile by running `sudo nano ~/.bash_profile`. Then run: `source ~/.bash_profile` +5. Run: `docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform` +6. When docker is done fetching the image, open http://dockerhost:8065/ in your browser. + +### Ubuntu ### +1. Follow the instructions at https://docs.docker.com/installation/ubuntulinux/ or use the summary below: + + ``` bash + sudo apt-get update + sudo apt-get install wget + wget -qO- https://get.docker.com/ | sh + sudo usermod -aG docker <username> + sudo service docker start + newgrp docker + ``` + +2. Start docker container: + + ``` bash + docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform + ``` + +3. When docker is done fetching the image, open http://localhost:8065/ in your browser. + +### Arch ### +1. Install Docker using the following commands: + + ``` bash + pacman -S docker + systemctl enable docker.service + systemctl start docker.service + gpasswd -a <username> docker + newgrp docker + ``` + +2. Start Docker container: + + ``` bash + docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform + ``` + +3. When Docker is done fetching the image, open http://localhost:8065/ in your browser. + +### Additional Notes ### +- If you want to work with the latest master from the repository (i.e. not a stable release) you can run the cmd: + + ``` bash + docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform:dev + ``` + +- Instructions on how to update your Docker image are found below. + +- If you wish to remove mattermost-dev use: + + ``` bash + docker stop mattermost-dev + docker rm -v mattermost-dev + ``` + +- If you wish to gain access to a shell on the container use: + + ``` bash + docker exec -ti mattermost-dev /bin/bash + ``` + +## Configuration Settings + +There are a few configuration settings you might want to adjust when setting up your instance of Mattermost. You can edit them in [config/config.json](config/config.json) or [docker/0.6/config_docker.json](docker/0.6/config_docker.json) if you're running a Docker instance. + +* *EmailSettings*:*ByPassEmail* - If this is set to true, then users on the system will not need to verify their email addresses when signing up. In addition, no emails will ever be sent. +* *ServiceSettings*:*UseLocalStorage* - If this is set to true, then your Mattermost server will store uploaded files in the storage directory specified by *StorageDirectory*. *StorageDirectory* must be set if *UseLocalStorage* is set to true. +* *ServiceSettings*:*StorageDirectory* - The file path where files will be stored locally if *UseLocalStorage* is set to true. The operating system user that is running the Mattermost application must have read and write privileges to this directory. +* *AWSSettings*:*S3*\* - If *UseLocalStorage* is set to false, and the S3 settings are configured here, then Mattermost will store files in the provided S3 bucket. + +### (Recommended) Enable Email + +The default single-container Docker instance for Mattermost is designed for product evaluation, and sets `ByPassEmail=true` so the product can run without enabling email, when doing so maybe difficult. + +To see the product's full functionality, [enabling SMTP email is recommended](doc/config/smtp-email-setup.md). + +## Upgrading Mattermost + +### Docker ### +To upgrade your Docker image to a preview of the latest stable release (NOTE: this will erase all data in the Docker container, including the database): + +1. Stop your Docker container by running: + + ``` bash + docker stop mattermost-dev + ``` +2. Delete your Docker container by running: + + ``` bash + docker rm mattermost-dev + ``` +3. Update your Docker image by running: + + ``` bash + docker pull mattermost/platform + ``` +4. Start your Docker container by running: + + ``` bash + docker run --name mattermost-dev -d --publish 8065:80 mattermost/platform + ``` + +To upgrade to the latest development build on master from the repository replace `mattermost/platform` with `mattermost/platform:dev` in the instructions 3) and 4) above. |