Skip to main content

​
Quickstart Guide

Get up and running with Mattermost in just a few minutes. This guide will help you deploy a Mattermost instance and send your first message.
This quickstart is designed for testing and development. For production deployments, see the Installation Guide.

​
Choose Your Path

Mattermost Cloud

Fastest Option: Managed hosting with zero infrastructure setup

Self-Hosted (Docker)

Developer-Friendly: Run locally or on your own server

​
Option 1: Mattermost Cloud (Fastest)

Get started in under 2 minutes with our fully managed cloud service.
1

Sign Up

Visit mattermost.com/sign-up and create your account.
  • Enter your work email
  • Choose your workspace name
  • Set your password
2

Create Your Team

After signing in, you’ll be prompted to:
  • Name your first team (e.g., “Engineering”, “Marketing”)
  • Invite team members via email (optional)
  • Select your team icon and display name
3

Create Your First Channel

Channels organize conversations by topic:
  1. Click the + icon next to “Channels” in the sidebar
  2. Choose Create New Channel
  3. Enter a channel name (e.g., “general”, “random”, “project-alpha”)
  4. Select Public or Private
  5. Click Create Channel
Public channels are visible to all team members. Private channels require an invitation.
4

Send Your First Message

You’re ready to communicate!
  1. Select your newly created channel
  2. Type a message in the text box at the bottom
  3. Press Enter to send
Try these features:
  • @mention team members with @username
  • Format text with markdown
  • Add emoji reactions by hovering over messages
  • Start a thread by clicking the reply icon
5

Download Mobile and Desktop Apps (Optional)

Stay connected on all devices:

​
Option 2: Self-Hosted with Docker

Run Mattermost locally using Docker for development and testing.

​
Prerequisites

  • Docker Engine 20.10+ and Docker Compose 2.0+
  • At least 2GB of available RAM
  • Ports 8065 (Mattermost) and 5432 (PostgreSQL) available
1

Create Docker Compose Configuration

Create a new directory for your Mattermost installation:
mkdir mattermost-docker && cd mattermost-docker
Create a docker-compose.yml file with the following configuration:
docker-compose.yml
services:
  postgres:
    image: postgres:14
    container_name: mattermost-postgres
    restart: always
    environment:
      POSTGRES_USER: mmuser
      POSTGRES_PASSWORD: mmuser_password
      POSTGRES_DB: mattermost
      POSTGRES_INITDB_ARGS: "--auth-host=scram-sha-256 --auth-local=scram-sha-256"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-h", "localhost"]
      interval: 5s
      timeout: 10s
      retries: 3

  mattermost:
    image: mattermost/mattermost-enterprise-edition:latest
    container_name: mattermost
    restart: always
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      # Database Configuration
      MM_SQLSETTINGS_DRIVERNAME: postgres
      MM_SQLSETTINGS_DATASOURCE: postgres://mmuser:mmuser_password@postgres:5432/mattermost?sslmode=disable&connect_timeout=10
      
      # Server Configuration
      MM_SERVICESETTINGS_SITEURL: http://localhost:8065
      MM_SERVICESETTINGS_ENABLELOCALMODE: "true"
    ports:
      - "8065:8065"
    volumes:
      - mattermost_config:/mattermost/config
      - mattermost_data:/mattermost/data
      - mattermost_logs:/mattermost/logs
      - mattermost_plugins:/mattermost/plugins
    healthcheck:
      test: ["CMD", "/mattermost/bin/mmctl", "system", "status", "--local"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  postgres_data:
  mattermost_config:
  mattermost_data:
  mattermost_logs:
  mattermost_plugins:
This configuration is based on the Mattermost server’s production Docker setup. For development, you can find additional compose files in server/docker-compose.yaml that include services like MinIO (S3-compatible storage), Redis, and Elasticsearch.
2

Start Mattermost

Launch all services with Docker Compose:
docker compose up -d
This command will:
  • Download the PostgreSQL 14 and Mattermost images
  • Create the database with user mmuser and database mattermost
  • Start Mattermost on port 8065
  • Create persistent volumes for data storage
Watch the logs to monitor startup: docker compose logs -f mattermost
3

Access Mattermost

Open your browser and navigate to:
http://localhost:8065
You should see the Mattermost setup wizard.
4

Create Administrator Account

On first launch, you’ll create the System Administrator account:
  1. Enter your email address
  2. Choose a username
  3. Set a strong password (minimum 8 characters)
  4. Click Create Account
Save these credentials securely - this account has full administrative privileges.
5

Create Your First Team

After account creation:
  1. Click Create a new team
  2. Enter a team name (e.g., “developers”)
  3. Choose a team URL (e.g., localhost:8065/developers)
  4. Click Finish
6

Create a Channel and Send Messages

You’ll automatically be in the “Town Square” channel (created by default).Create a new channel:
  1. Click the + icon next to “Channels”
  2. Select Create New Channel
  3. Enter a name (e.g., “general”)
  4. Add a purpose/description (optional)
  5. Choose Public or Private
  6. Click Create Channel
Send your first message:
Hello, Mattermost! 👋
Try advanced features:
  • Code blocks: Use triple backticks for code
func main() {
    fmt.Println("Hello from Mattermost!")
}
  • Mentions: Use @username to notify users
  • Slash commands: Type /help to see available commands
  • File uploads: Drag and drop files into the message box
7

Invite Team Members (Optional)

Main Menu → Invite PeopleOptions:
  • Send email invitations
  • Share team invite link
  • Use LDAP/SAML for enterprise auth (requires configuration)

​
Managing Your Docker Instance

Stop Mattermost: 
docker compose stop
Restart Mattermost: 
docker compose restart
View logs: 
docker compose logs -f mattermost
Access Mattermost CLI (mmctl): 
docker exec -it mattermost /mattermost/bin/mmctl --local
Remove everything (including data): 
docker compose down -v
The -v flag removes volumes, which permanently deletes all data.

​
What’s Next?

Configure Mattermost

System Console → Settings
  • Email notifications
  • File storage (S3, MinIO)
  • Authentication (LDAP, SAML, OAuth)
  • Plugins and integrations

Install Plugins

System Console → Plugins → Plugin MarketplacePopular plugins:
  • GitHub
  • Jira
  • Zoom
  • GitLab

Production Deployment

Learn about:
  • High availability clustering
  • SSL/TLS configuration
  • Database optimization
  • Backup strategies

API & Integrations

Build custom integrations:
  • REST API
  • WebSocket API
  • Webhooks
  • Slash commands

​
Troubleshooting

Check logs:
docker compose logs mattermost
Common issues:
  • Port 8065 already in use: Change the port mapping in docker-compose.yml
  • Database connection failed: Ensure PostgreSQL is healthy with docker compose ps
  • Permission issues: Check volume permissions
  • Verify Mattermost is running: docker compose ps
  • Check if port 8065 is accessible: curl http://localhost:8065
  • Ensure no firewall is blocking the port
  • If using a VM, ensure port forwarding is configured
Reset using mmctl:
docker exec -it mattermost /mattermost/bin/mmctl --local user reset-password [email protected]
The connection string format is:
postgres://mmuser:mmuser_password@postgres:5432/mattermost?sslmode=disable&connect_timeout=10
  • Verify credentials match in both containers
  • Ensure PostgreSQL is healthy
  • Check network connectivity between containers

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us