Preview: Documenting config.json settings (pre-Mattermost v1.0)

As part of the Admin Console epic, we have a ticket for refactoring and documenting existing config settings.

Below is a draft of the comments proposed to be added to config settings, which will then make their way to Admin Console UI after some reorganization.

Feedback, questions, suggestions and comments highly welcome on any setting below.

Note:

  1. Setting currently defined in config.js will be refactored into config.json that will be used in future to generate config.js dynamically.

  2. Some settings in config.json in Beta1 may be refactored in Beta2 so we can make things more straight forward for final release.

    “LogSettings”: {

    “ConsoleEnable”: true,
    /* Typically set to “false” in production. Developers may set this field to true to output log messages to console based on ConsoleLevel option. */

    “ConsoleLevel”: “DEBUG”,
    /* This setting determines the level of detail at which log events are written to the console when ConsoleEnable=true. ERROR: Outputs only error messages. INFO: Outputs error messages and information around startup and initialization. DEBUG: Prints high detail for developers debugging issues working on debugging issues. */

    “FileEnable”: true,
    /* Typically set to true in production. true: log files are written to files specified in FileLocation, and to /logs if FileLocation is blank. */

    “FileLevel”: “INFO”,
    /* This setting determines the level of detail at which log events are written to log files when ConsoleEnable=true. ERROR: Outputs only error messages. INFO: Outputs error messages and information around startup and initialization. DEBUG: Prints high detail for developers debugging issues working on debugging issues. */

    “FileFormat”: “”,
    /*
    Format of log message output. If blank, FileFormat = “[%D %T] [%L] (%S) %M”, where:

     %T	Time (15:04:05 MST) 
     %t	Time (15:04) 
     %D	Date (2006/01/02) 
     %d	Date (01/02/06) 
     %L	Level (FNST, FINE, DEBG, TRAC, WARN, EROR, CRIT) 
     %S	Source 
     %M	Message 
    

    */

    “FileLocation”: “”
    /* Director to which log files are written. If blank, log files write to /logs. */
    },

    “ServiceSettings”: {

    "SiteName": "Mattermost", 
    /* Name of service shown in login screens and UI */ 
    
    "Mode" : "dev", 
    /* To be deprecated, previously used for local development */
    
    "AllowTesting" : false, 
    /* Enables external APIs and slash commands for testing. Typically used for product development */
    
    "UseSSL": false, 
    /* "true": redirects non-SSL requests to SSL requests. To be deprecated and replaced by documentation for using load balancer or proxy server (e.g. ngnix) to configure redirect. */
    
    "Port": "8065", 
    /* Default port on which Mattermost service runs */
    
    "Version": "developer", 
    /* Release version number configured in build process. On master, version number is set to “developer” */
    
    "Shards": {
    }, 
    /* To be deprecated */
    
    "InviteSalt": "gxHVDcKUyP2y1eiyW8S8na1UYQAfq6J6", 
    /* 32-character (to be randomly generated via Admin Console) salt added to email invites and signed. */ 
    
    "PublicLinkSalt": "TO3pTyXIZzwHiwyZgGql7lM7DG3zeId4", 
    /* 32-character (to be randomly generated via Admin Console) salt added to team invite links and signed. */ 
    
    "ResetSalt": "IPxFzSfnDFsNsRafZxz8NaYqFKhf9y2t", 
    /* 32-character (to be randomly generated via Admin Console) salt added to password reset link and signed. */ 
    
    "AnalyticsUrl": "", 
    /* To be deprecated, was previously use for SnowPlow Analytics. */
    
    "UseLocalStorage": true, 
    /* "true": stores files uploaded by end users locally. false: store files using S3 (see S3 storage parameters ). */
    
    "StorageDirectory": "./data/", 
    /* Directory used to store files locally when UseLocalStorage=true. */
    
    "AllowedLoginAttempts": 10, 
    /* Login attempts allowed before user is locked out and required to reset password via email. */
    
    "DisableEmailSignUp": false 
    /* true: Disable option to sign-up for new team or new user account using email */
    

    },

    “SSOSettings”: {

    "gitlab": {
    
        "Allow": false, 
        /* 
             true: GitLab single-sign-on option appears on team creation, user sign-up, user sign-in pages. 
             
             To set up GitLab SSO: 
        
             1. Login to your GitLab account and go to the Applications section either in Profile Settings or Admin Area.
             
             2. Add a new application called "Mattermost" with the following as Redirect URIs:
             
                 <your-mattermost-url>/login/gitlab/complete (example: http://localhost:8065/login/gitlab/complete)
                 
                 <your-mattermost-url>/signup/gitlab/complete
                 
             3. Submit the application and copy the given Id and Secret into the appropriate SSOSettings fields in config/config.json
    
             4. Also in config/config.json, set Allow to true for the gitlab section, leave Scope blank (Scope is used by some SSO providers to limit the user account information to access, for example Google might set scope to "email profile". GitLab SSO does not implement Scope) and use the following for the endpoints:
    
                 AuthEndpoint: <your-gitlab-url>/oauth/authorize (example http://localhost:3000/oauth/authorize)
                 TokenEndpoint: <your-gitlab-url>/oauth/token
                 UserApiEndpoint: <your-gitlab-url>/api/v3/user
                 
             5. (Optional) If you would like to force all users to sign-up with GitLab only, in the ServiceSettings section of config/config.json please set AllowEmailSignUp to false.
    
             6. Restart your Mattermost server to see the changes take effect.
        
        */
    
        "Secret" : "", 
    
        "Id": "", 
    
        "Scope": "", 
    
        "AuthEndpoint": "",
    
        "TokenEndpoint": "",
    
        "UserApiEndpoint": "" 
    }
    

    },

    “SqlSettings”: {

    "DriverName": "mysql", 
    /* "mysql": enables driver to MySQL database; "postgres": enables driver to PostgreSQL database. */
    
    "DataSource": "mmuser:mostest@tcp(dockerhost:3306)/mattermost_test?charset=utf8mb4,utf8", 
    /* when DriverName set to "postgres" then use a connection string in the form “postgres://mmuser:password@localhost:5432/mattermost_test?sslmode=disable&connect_timeout=10”
    
    "DataSourceReplicas":  ["mmuser:mostest@tcp(dockerhost:3306)/mattermost_test?charset=utf8mb4,utf8"], 
    /* Read replicas of MySQL or PostgreSQL database.  If running a single server set to DataSource */
    
    "MaxIdleConns": 10, 
    /* Maximum number of idle connections held open to the database. */
    
    "MaxOpenConns": 10, 
    /* Maximum number of open connections held open to the database. */
    
    "Trace": false, 
    /* "true": Output executing SQL statements to console. Typically used for development. */
    
    "AtRestEncryptKey": "Ya0xMrybACJ3sZZVWQC7e31h5nSDWZFS" 
    /* 32-character (to be randomly generated via Admin Console) salt available to encrypt and decrypt sensitive fields in database. */ 
    

    },

    “AWSSettings”: {

    "S3AccessKeyId": "", 
    /* When UseLocalStorage=false, set up S3 storage using the following instructions:  http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSGettingStartedGuide/AWSCredentials.html */
    
    "S3SecretAccessKey": "", 
    /* When UseLocalStorage=false, set up S3 storage using the following instructions:  http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSGettingStartedGuide/AWSCredentials.html */
    
    "S3Bucket": "", 
    /* Name you selected for your S3 bucket in AWS, e.g. “mattermost-media”. */
    
    "S3Region": "" 
    /* AWS region you selected for creating your S3 bucket, e.g. us-east-1. */ 
    

    },

    “ImageSettings”: {

    "ThumbnailWidth": 120, 
    /* Width of thumbnails generated from uploaded images. Updating this value changes how thumbnail images render in future, but does not change images created in the past. */
    
    "ThumbnailHeight": 100, 
    /* Height of thumbnails generated from uploaded images. Updating this value changes how thumbnail images render in future, but does not change images created in the past. */
    
    "PreviewWidth": 1024, 
    /* Maximum width of preview image. Updating this value changes how preview images render in future, but does not change images created in the past. */
    
    "PreviewHeight": 0, 
    /* Maximum height of preview image ("0": Sets to auto-size). Updating this value changes how preview images render in future, but does not change images created in the past. */
    
    "ProfileWidth": 128, 
    /* Width of profile pic */
    
    "ProfileHeight": 128, 
    /* Height of profile pic */
    
    "InitialFont": "luximbi.ttf" 
    /* Font used in auto-generated profile pics with colored backgrounds */
    

    },

    “EmailSettings”: {

    "ByPassEmail" : true, 
    /* 
         "false": email enabled and users required to verify email addresses to create accounts. 
         "true": no email available, no email verification required to create accounts, and no password reset available. Typically used in preview mode. 
    */
    
    "SMTPUsername": "", 
    /* Obtain this credential from administrator setting up your email server. */ 
    
    "SMTPPassword": "", 
    /* Obtain this credential from administrator setting up your email server. */ 
    
    "SMTPServer": "", 
     /* Location of SMTP email server. */
    
    "UseTLS": false, 
    /* To be refactored. Currently "true" enables TLS encryption for email. */
    
    "UseStartTLS": false, 
    /* To be refactored. Currently "true" enables TLS encryption on start for email. Mutually exclusive with UseTLS */
    
    "FeedbackEmail": "", 
     /* Email displayed on email account used when sending notification emails from Mattermost system. */
    
    "FeedbackName": "", 
     /* Name displayed on email account used when sending notification emails from Mattermost system. */
    
    "ApplePushServer": "", 
    /* Settings for features in development. */
    
    "ApplePushCertPublic": "", 
    /* Settings for features in development. */
    
    "ApplePushCertPrivate": "" 
    /* Settings for features in development. */     
    

    },

    “RateLimitSettings”: {

    "UseRateLimiter": true, 
    /* "true": Throttles rate at which APIs response */
    
    "PerSec": 10, 
    // if UseRateLimiter=true, throttles API at this number of requests per second. */
    
    "MemoryStoreSize": 10000, 
    /* Maximum number of users sessions connected to the system as determined by VaryByRemoteAddr and VaryByHeader variables. */
    
    "VaryByRemoteAddr": true, 
    /* "true": Rate limit API access by count of IP address. */
    
    "VaryByHeader": "" 
    /* When filled in, vary rate limiting by header field specified (e.g. when configuring ngnix set to “X-Real-IP” and VaryByRemoteAddr=false, when configuring AmazonELB set to “X-Forwarded-For” and VaryByRemoteAddr=false). */
    

    },

    “PrivacySettings”: {

    "ShowEmailAddress": true, 
    /* "false": Hides email address of users from other users including team administrator. */
    
    "ShowPhoneNumber": true, 
    /* To be deprecated. */
    
    "ShowSkypeId": true,        
    /* To be deprecated. */
    
    "ShowFullName": true 
    /* To be deprecated. */
    

    },

    “TeamSettings”: {

    "MaxUsersPerTeam": 150, 
    /* Maximum number of users per team */
    
    "AllowPublicLink": true, 
    /* "true": Allow users to share public links to files and images. */
    
    "AllowValetDefault": false, 
    /* To be deprecated. */
    
    "TermsLink": "/static/help/configure_links.html", 
    /* Link to terms of service. Defaults to placeholder page. */
    
    "PrivacyLink": "/static/help/configure_links.html", 
    /* Link to privacy policy. Defaults to placeholder page. */
           
    "AboutLink": "/static/help/configure_links.html", 
    /* Link to About page. Defaults to placeholder page. */
    
    "HelpLink": "/static/help/configure_links.html", 
    /* Link to Help page. Defaults to placeholder page. */
    
    "ReportProblemLink": "/static/help/configure_links.html", 
    /* Link to Report a Problem page. Defaults to placeholder page. */
    
    "TourLink": "/static/help/configure_links.html", 
    /* Link to Tour page. Defaults to placeholder page. */
    
    "DefaultThemeColor": "#2389D7", 
    /* Default theme color for team sites. */
    
    "DisableTeamCreation": false, 
    /* "true": Ability to create teams is disabled. Create team button displays error when pressed. */
    
    "RestrictCreationToDomains": "" 
    /* When ByPassEmail=false, teams can only be created by verified email from a specific domain (e.g. "mattermost.org") or list of comma-separated domains (e.g. "corp.mattermost.com, mattermost.org"). */
    

    }

config.js:

var config = {

// LOGGLY CONFIGS 

LogglyWriteKey: "",  
/* To be deprecated. */

LogglyConsoleErrors: true, 
/* To be deprecated. */

// SEGMENT CONFIGS

SegmentWriteKey: "", 
/* For users running a SaaS services, sign up for a WriteKey at Segment.com to track metrics. */

// FEATURE SWITCHES 

AllowPublicLink: true, 
/* "true": enables UI of sharing public links. */

AllowInviteNames: true, 
/* "true": Offer ability to set first and last names on invite by email. */

RequireInviteNames: false, 
/* To be deprecated--unnecessary. "true": When AllowInviteNames=true, require first and last name fields to be filled out in order to invite new users by email */ 

AllowSignupDomainsWizard: false, 
/* "true": Enable team sign-up wizard screen to restrict team member signup to specific email domains, and enable/disable invite by email and enable/disable invite by web link. */

GoogleDeveloperKey: "", 
/* Set this key to enable embedding of YouTube video previews based on hyperlinks appearing in messages or comments. Instructions to obtain a GoogleDeveloperKey available here: https://www.youtube.com/watch?v=Im69kzhpR3I. Leaving field blank disables the automatic generation of YouTube video previews from links. */ 

ShowEmail: true, 
/* "false": Hides email address of users from other users including team administrator. */

// LINKS 

"TermsLink": "/static/help/configure_links.html", 
/* Link to terms of service. Defaults to placeholder page. */

"PrivacyLink": "/static/help/configure_links.html", 
/* Link to privacy policy. Defaults to placeholder page. */
          
"AboutLink": "/static/help/configure_links.html", 
/* Link to About page. Defaults to placeholder page. */

"HelpLink": "/static/help/configure_links.html", 
/* Link to Help page. Defaults to placeholder page. */

"ReportProblemLink": "/static/help/configure_links.html", 
/* Link to Report a Problem page. Defaults to placeholder page. */

HomeLink: "", 
/* To be deprecated. */ 

ShowTermsDuringSignup: false, 
/* "true": Show message about agreeing to the Terms of Service during the team sign-up and account sign-up process. */

ThemeColors: ["#2389d7", "#008a17", "#dc4fad", "#ac193d", "#0072c6", "#d24726", "#ff8f32", "#82ba00", "#03b3b2", "#008299", "#4617b4", "#8c0095", "#004b8b", "#004b8b", "#570000", "#380000", "#585858", "#000000"]
/* Default theme color options. */     

};

// FLAVOR TEXT STRINGS

var strings = {
Team: “team”,
TeamPlural: “teams”,
Company: “company”,
CompanyPlural: “companies”
};
/* To be deprecated. */

Most of this documentation is great and should definitely be included. Many items are “self explanatory” but when something doesn’t work even experienced admins will find themselves reading values more than once wondering if they might affect their problem.

The Gitlab SSO area could use some improvement however. As I noted on the repo commit there is some ambiguity about what URL is desired there, especially when there is more than one possibility as in when SSL and/or a public facing proxy is involved.

Hi @alerque,

High appreciate the feedback, and your active participation in the community. We’ve just drafted new documentation to request help from the community to help improve our documentation.

I wondered if you might be interested in expanding your role and helping us with a pull request to clarify our GitLab SSO documentation for future users?

@it33 If the documentation isn’t fixed by the time I figure it out myself I’ll definitely consider putting together a PR. At the moment I don’t have a working instance myself yet. My comment about the documentation being unclear stems from the fact that I had doubts about whether that was the part of my config that was broken or not. After I get that figured out and try a few setups on for size I might be in a position to make the documentation more explicit.

Frankly it seems the universal assumption is that everybody is going to want to run Docker and so far only a handful of us seem to have even tried it on bare metal servers with the service running directly on the host. The pain points and hence what needs to be documented are pretty different and at least until a few more distro packagers pick this up we’re kind of stabbing in the dark. (BTW I’m helping to sort out an ArchLinux package for this.)

Thanks @alerque, highly appreciate both the Arch Linux package and all your help and interest in Mattermost so far. We have an early draft of production install instructions outside of Docker and are sequencing documentation in the product for after the admin console is setup, since there’s been some refactoring of config files for Oct 2 release.

Docker was a good starting point, completely agree bare metal installs are a priority.

Hi,

I’m working on a non-Docker install right now. This guide could be really useful, but probably 50% of these options have at least different names (and possibly different functionality) as of the v1.0.0 release. They could stand to be updated.