## 1. Project Overview & Quickstart (requarks/values.yaml) # values.yaml Open-source repository requarks/values.yaml ### Repository Details - **Repository:** [requarks/values.yaml](https://github.com/requarks/values.yaml) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (requarks/docs) ## File: wiki/admin-guide/install-debian-8.md This installation guide is based on a new Debian 8 instance from DigitalOcean / Vultr. # Create user Let's create a new user for running Wiki.js: `adduser wiki` # Install MongoDB Follow the official installation guide: https://docs.mongodb.com/manual/tutorial/install-mongodb-on-debian/ # Install Git The latest git package available for Debian 8 is outdated and cannot be used. We'll compile the latest release from source. It is recommended to use the latest version available by looking at the https://github.com/git/git/releases page. Simply replace the version number in the instructions below. ```sh # Remove existing git package: apt-get remove git # Install build requirements: apt-get install libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev build-essential autoconf # Fetch and build Git cd /tmp curl -L --progress https://github.com/git/git/archive/v2.13.1.tar.gz | tar xz cd git-2.13.1/ make configure ./configure make prefix=/usr/local all make prefix=/usr/local install # Confirm this command returns /usr/local/bin/git: which git ``` # Install Node.js Install the LTS version of Node.js: ```sh curl -sL https://deb.nodesource.com/setup_6.x | bash - apt-get install -y nodejs ``` # Install sudo **If sudo is already installed and configured, skip this step.** 1. Install sudo: `apt install sudo` 2. Add the wiki user to sudo group: `adduser wiki sudo` 3. Edit the sudoers file: `nano /etc/sudoers` - Add the following line `wiki ALL=(ALL:ALL) ALL` right after `%sudo ALL=(ALL:ALL) ALL` - Ctrl-X to save. 4. Disconnect from your SSH / Terminal session and reconnect. # Install Wiki.js 1. Login as the wiki user: `sudo -i -u wiki` 2. Create a folder to install Wiki.js: `mkdir wiki` 3. Go inside the folder: `cd wiki` 4. Install Wiki.js: `curl -sSo- https://wiki.js.org/install.sh | bash` 5. Follow the instructions to complete the installation. --- ## File: wiki/admin-guide/manage-access-rights.md # What are access rights? When you create or authorize a user in the system, that user has read-only permissions on all pages. Access rights is a list of permissions that are assigned to a user which define what he can or cannot do. # View access rights From the **Users** page, click on the **name** of the account you want to view. A section is titled **Access Rights**, which lists the current access rights of the user: # Manage access rights A user can have as many access rights as needed. For example, you may want the user to be able to read any page but only create / edit a few. An access right rule consists of 4 parts: - **Permission**: Defines what the user can do. - **Path precision**: Whether the path entered should match precisly (Path match exactly) or only match the beginning (Path starts with). - **Path**: The actual path - **Allow / Deny**: Allow means the rule will be applied. Deny means the user will not be able to access the page. By default, a user has `Read Only` (permission) to all pages that `starts with` (path precision) the path `/` (path). To allow a user to create and edit any page on the site, simply change that permission to **Read and Write**. ## Add a new rule To provide granular access to a user, you can add as many rules as you need. Rules are additive, with the Deny action having priority. Given this example: - The user can read any page, with the exception of all pages that starts with `/violin`. - The user can edit (and create) the page `/piano`, but not `/pianos` or `/piano/studio-grand` - The user cannot read, create or edit any page that begins with `/violin`. Therefor, he can read the page `/viola` but not `/violin/strings` Click **Save Changes** to save the new rules. ## Remove a rule Simply click the red **X** button next to the rule to delete. Click **Save Changes** to save the updated rules. --- ## File: wiki/admin-guide/manage-users.md # List all users - Click on **Account** from the sidebar. - Click on **Users** from the sidebar. A list of all users authorized to login will be displayed. # Create a new local user A local user is stored in the Wiki.js database. This authentication method is enabled by default and is used for the root administrator. To create a new user, click on the **Create / Authorize User** button in the top right corner of the **Users** page. **Fill in** the fields and click **Create User**. # Authorize a social user A social user is authenticated using Microsoft, Google or Facebook login mechanisms. It provides convenience for users by not having to remember yet another login. To authorize a social user to login to Wiki.js, click on the **Create / Authorize User** button in the top right corner of the **Users** page. **Fill in** the email address of the user and select the social provider in the **Provider** dropdown menu. Finally, click the **Authorize User** button. # Edit a user To edit information about a user, click on its name from the **Users** page list. Note that the email address cannot be modified as this is the unique identifier of the user. If the email address of a user changed, you must create a new account and delete the old one if necessary. Read the [Manage Access Rights](/wiki/admin-guide/manage-access-rights) page to learn how to provide the necessary access rights to a user. # Delete a user To delete (or de-authorize) a user, click on its name from the **Users** page list. Click on the red **Delete Account** button at the bottom right of the page. --- ## File: wiki/admin-guide/setup-nginx.md Below are example configurations that can be used as a reverse proxy setup for Wiki.js. # Sample NGINX configurations ## HTTP reverse-proxy example ```makefile server { listen 80; listen [::]:80; server_name wiki.example.com; location / { proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_pass http://127.0.0.1:3001; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_next_upstream error timeout http_502 http_503 http_504; } } ``` ## HTTPS reverse-proxy example ```makefile server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name wiki.example.com; ssl_session_timeout 1d; ssl_session_cache shared:SSL:50m; ssl_session_tickets off; ssl_protocols TLSv1 TLSv1.1 TLSv1.2; ssl_ciphers "EECDH+ECDSA+AESGCM EECDH+aRSA+AESGCM EECDH+ECDSA+SHA384 EECDH+ECDSA+SHA256 EECDH+aRSA+SHA384 EECDH+aRSA+SHA256 EECDH EDH+aRSA !RC4 !aNULL !eNULL !LOW !3DES !MD5 !EXP !PSK !SRP !DSS"; ssl_prefer_server_ciphers on; ssl_certificate /etc/nginx/ssl/wiki.example.com/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/wiki.example.com/privkey.pem; ssl_trusted_certificate /etc/nginx/ssl/wiki.example.com/chain.pem; location / { proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_pass http://127.0.0.1:3001; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_next_upstream error timeout http_502 http_503 http_504; } } ``` --- ## File: wiki/docker/compose.md # Prerequisites - Docker # Create config file 1) Create a copy of the [sample config file](https://github.com/Requarks/wiki-v1/blob/master/config.sample.yml) on your host. 2) Modify the config file with your own settings. Make sure to set the `db` parameter to point to the mongo container. In the example docker compose file, the mongo container is named `wikidb`. As such, the `db` connection string should be set to: `mongodb://wikidb:27017/wiki` # Create Docker Compose file 1) Create a copy of the [sample Docker Compose](https://github.com/Requarks/wiki-v1/blob/master/tools/docker-compose.yml) file. 2) Change the `ports` port to match the port entered in your config.yml file. 3) Replace the `WIKI_ADMIN_EMAIL` parameter value with the email of the administrator account. This account will be created when run the first time. 4) Replace the `./config.yml` value with the path of your config file created earlier. It will be linked to your docker container. Do **not** change the path of the config file inside the container (`/var/wiki/config.yml`)! 5) Change the local path of the MongoDB data folder (`./data/mongo`) if necessary. Do **not** change the path of the data folder inside the mongo container (`/db/data`)! # Run the container It's now time to run the containers as defined in the previous step: ```bash sudo docker-compose up ``` # First login An administrator account is created the first time you run the container. The default password is `admin123`. Change it upon login! --- ## File: wiki/docker/dockerfile.md # Prerequisites - Docker - A MongoDB database server (either running inside another container or on a remote machine) # Create config file 1) Create a copy of the [sample config file](https://github.com/Requarks/wiki-v1/blob/master/config.sample.yml) on your host. 2) Modify the config file with your own settings. # Create Dockerfile 1) Create a copy of the [sample Dockerfile](https://github.com/Requarks/wiki-v1/blob/master/tools/Dockerfile). 2) Replace the `WIKI_ADMIN_EMAIL` parameter value with the email of the administrator account. This account will be created when run the first time. 3) Replace the `your-config.yml` value with the name of your config file created earlier. This file must be located in the same folder as your Dockerfile if not providing the full path. It will be copied inside your docker container. 4) Change the `EXPOSE` port to match the port entered in your config.yml file. # Build the image From a command prompt in the same folder as your Dockerfile, execute the following command to build your Dockerfile: ```bash sudo docker build -t wiki . ``` # Run the container It's now time to run the container from the image created in the previous step: ```bash sudo docker run -p 8080:3000 wiki ``` The `-p` parameter above is optional. Define it if you want to re-map the exposed port to something else. # First login An administrator account is created the first time you run the container. The default password is `admin123`. Change it upon login! --- ## File: wiki/install/authentication.md {.pagelogo} Wiki.js supports multiple authentication providers. You may choose to enable one, some or even all of them. > :warning: You must have at least 1 provider enabled as edits can only be performed while authenticated. {.is-warning} # Local The local provider stores user accounts in the wiki database. It does not rely on any 3rd party service and accounts are unique to your wiki. This is the most simple solution and **is enabled by default**. # Microsoft Account The Microsoft Account provider lets users login using their own Microsoft account. 1. Go to https://account.live.com/developers/applications/index 2. **Create** a new application (e.g. Wiki). 3. Under **Properties**, take note of the generated **Application Id**. 4. Under **Application Secrets**, click on **Generate New Password**. Take note of the provided password! It will not be shown again. 5. Under **Platforms**, click on **Add Platform**. Choose **Web**. 6. A **Redirect URIs** field just appeared. Enter the **full URL** of your wiki followed by `/login/ms/callback` as e.g.: `https://www.example.com/login/ms/callback` 7. Under **Microsoft Graph** > **Delegated Permissions**, click **Add**. 8. Find entry **User.ReadBasic.All** and **check** it, then click **Ok**. You should now have both **User.Read** and **User.ReadBasic.All** listed. 9. *(optional)* Add a logo, terms of service and privacy statement URLs if needed. 10. Click **Save**. Under the auth section of your config.yml, you can now enter the required info: ```yaml microsoft: enabled: true clientId: YOUR_APPLICATION_ID clientSecret: YOUR_APPLICATION_PASSWORD ``` # Google ID The Google ID provider lets users login using their own Google ID. 1. Go to https://console.cloud.google.com/ 2. **Create** a new Project (e.g. Wiki). 3. From the sidebar menu, click **API Manager**. 4. Click on the **Enable API** button. 5. Enable the **Google+ API**. 6. From the sidebar menu, click **Credentials**. 7. Under the **OAuth consent screen** tab, **fill in** the required info and click **Save**. 8. Back to the **Credentials** tab, click on **Create credentials** > **OAuth client Id**. 9. Choose **Web Application** and enter a **name** (e.g. Wiki). 10. Under **Restrictions**, enter the **authorised origin domain** of your wiki (e.g. https://www.example.com) and the **authorised redirect URL** (full URL of your wiki followed by `/login/google/callback` as e.g.: `http://www.example.com/login/google/callback`) 11. Click **Create** and take note of both the generated **Client ID** and **Client Secret**. Under the auth section of your config.yml, you can now enter the required info: ```yaml google: enabled: true clientId: YOUR_CLIENT_ID clientSecret: YOUR_CLIENT_SECRET ``` # Facebook The Facebook provider lets users login using their own Facebook account. 1. Go to https://developers.facebook.com 2. Choose 'Add a New App' 3. Your app id should be clearly visible on the top of the page. To get your app secret, go to the 'Dashboard' and click 'Show' next to the starred-out secret 4. You can now test logging in with your own account and users you explicitly give access. To open up logging in via your app to everyone, make your app 'public' under 'App Review'. Under the auth section of your config.yml, you can now enter the required info: ```yaml facebook: enabled: true clientId: YOUR_FACEBOOK_APP_ID clientSecret: YOUR_FACEBOOK_APP_SECRET ``` # GitHub The GitHub provider lets users login using their own GitHub account. 1. Go to https://github.com/settings/applications/new 2. Enter an **Application Name** (e.g. Wiki). 3. Enter the **Homepage URL** to your wiki. 4. In the **Authorization Callback URL** field, enter the full URL of your wiki followed by `/login/github/callback` (e.g.: `http://www.example.com/login/github/callback`). 5. Click on **Register Application**. 6. Take note of both the generated **Client ID** and **Client Secret**. 7. (optional) Upload a logo for your application. Under the auth section of your config.yml, you can now enter the required info: ```yaml github: enabled: true clientId: GITHUB_CLIENT_ID clientSecret: GITHUB_CLIENT_SECRET ``` # Slack The Slack provider lets users login using their own Slack account. 1. Go to https://api.slack.com/apps 2. Click on **Create an App**. 3. Enter a name under **App Name** (e.g. Wiki) and select a **Development Slack Team**. 4. Click on **Create App**. 5. In the left sidebar, navigate to **OAuth & Permissions**. 6. Under **Redirect URLs**, click **Add a New Redirect URL** and enter the full URL of your wiki followed by `/login/slack/callback` (e.g.: `http://www.example.com/login/slack/callback`). 7. Click **Add** and then **Save URLs**. 8. Under **Permissions**, add the following scopes: **identity.basic** and **identity.email** 9. **Save Changes** and navigate to **Basic Information** in the left sidebar. 10. Take note of the **Client ID** and **Client Secret** shown under **App Credentials**. 11. (optional) Upload a logo and customize the look and description of your app. > :warning: Quote your slack client ID otherwise it will be treated as float instead as a string and this will cut it off. {.is-warning} Under the auth section of your config.yml, you can now enter the required info: ```yaml slack: enabled: true clientId: SLACK_CLIENT_ID clientSecret: SLACK_CLIENT_SECRET ``` # LDAP (Active Directory) The LDAP provider lets users login using their LDAP / Active Directory account. This provider is only for classic LDAP / Active Directory systems, it is **not** compatible with Azure Active Directory. Use the **Azure Active Directory** provider instead (coming soon). Under the auth section of your `config.yml`, enter the required info: ```yaml ldap: enabled: true url: ldap://serverhost:389 bindDn: cn='root' bindCredentials: BIND_PASSWORD searchBase: o=users,o=example.com searchFilter: (uid={{username}}) tlsEnabled: false tlsCertPath: C:\example\root_ca_cert.crt ``` The `searchFilter` option has a variable `{{username}}` which contains the value entered by the user during login. You can use this variable however you want in your searchFilter expression. For Active Directory, you should usually use the `samaccountname` in the `searchFilter`, e.g.: `(samaccountname={{username}})` The user must have an email address associated with the account, or sign in will fail. This holds true regardless of `searchFilter` configuration. # Azure Active Directory The Azure AD provider lets users login using their Azure Active Directory (AAD) account. This provider is only for Azure AD, it is **not** compatible with LDAP / classic Active Directory. Use the **LDAP (Active Directory)** provider instead. 1. Login to your [Azure AD Portal.](https://portal.azure.com) 2. Click on **Azure Active Directory**. 3. On the left menu bar, select **App Registrations**. 4. Create a new application integration with **New application registration**. 5. Name it something useful like *Wiki* and make sure the application type is *Web app / API*. 6. Your *Sign-on URL* will be the full domain of your Wiki followed by `/login/azure/callback`. e.g `https://portal.example.com/login/azure/callback` 7. Click **Create**. 8. You will then see your application in the **App registrations** menu. Click on it. 9. The *Application ID* will be given to you. Add this to your `config.yml` as *clientId*. 10. A private app key will need to be generated now. Under **Settings** there will be a **Keys** option. Click on that. There should be no keys present. Write in a description for the key in **Key Description** and set a **Duration**. Something like *wiki_priv* and *Never expires* is fine. 11. Click **Save**. Your private key will now be generated. Copy the key's value and add it to *clientSecret* in your `config.yml`. Be careful to note this down as this will be the only time that you see it. 12. Make sure that in **Reply URLs** it contains your `https://portal.example.com/login/azure/callback` or the integration won't work. You must be using SSL on your Wiki site for Microsoft to allow the API integration. 13. Check to make sure that correct permissions have been granted. Under the App Registration **Settings**, select the **Required Permissions** option. Select the *Windows Azure Active Directory* object. From here, make sure that *Sign in and read user profile* under **Delegated Permissions** is ticked. 14. Your tenant ID is your `example.onmicrosoft.com`. Note: your regular domain `example.com` will not work here as it needs to be the Microsoft Azure AD name. Alternatively, you can find your tenant ID string via **Azure Active Directory** -> **Properties** -> **Directory ID**. ```yaml azure: enabled: true clientId: YOUR_CLIENT_ID clientSecret: YOUR_CLIENT_SECRET resource: '00000002-0000-0000-c000-000000000000' tenant: YOUR_TENANT_ID_OR_AD_DOMAIN ``` Note: If you are receiving a *User Email Not Found* error from Wiki.js after trying to login with your Azure AD Credentials, this is a known bug and being worked on. The bug is described [here](https://github.com/Requarks/wiki/issues/307) and a solution is provided in the thread. --- ## File: wiki/install/configuration.md {.pagelogo} The configuration file is automatically generated for you during the Configuration Wizard. You may however change settings or additional options not shown during the wizard, based on the list below. The configuration file is located at the root, named `config.yml`. Environment variables can be used to set property values with the syntax `$(ENV_VAR_NAME)`. **Note that any changes will not be applied until Wiki.js is restarted**. # General Site Settings | Property | Required | Description | Default Value | |---------------------|:--------:|--------------------------------------------------------------------------------------------------------------------------------------|:----------------:| | **title** | yes | The title of the website. Displayed in the navigation bar. | Wiki | | **host** | yes | The full hostname of the site, as accessed by the user. Do not add a trailing slash. You must add the port if you expect users to access your wiki via a non-standard port. | http://localhost | | **port** | no | The port on which the server should listen to. You can also use the environment variable PORT using $(PORT). | 80 | | **paths.repo** | yes | The path (absolute or relative to server.js) to the folder where markdown content will be synchronized with the Git repository. Make sure this folder has the necessary write permissions. Note that this folder will contain all uploads (images, documents, etc.), so make sure to allow enough disk space depending on your usage. | ./repo | | **paths.data** | yes | The path (absolute or relative to server.js) to the folder where temporary data will be stored (cache, thumbnails, search indexes, etc.). Make sure this folder has the necessary write permissions. | ./data | | **lang** | yes | The default language to use for the site UI. Possible values: `en`, `es`, `fr`, `ko`, `pt`, `ru` or `zh` | en | # Authentication Wiki.js offers various authentication providers that you can enable. See the [authentication guide](/wiki/install/authentication) to learn how to get the necessary info for each provider. | Property | Required | Description | Default Value | |---------------------|:--------:|--------------------------------------------------------------------------------------------------------------------------------------|:----------------:| | **public** | yes | Should the wiki be accessible publicly without a login. If set to true, creates a Guest user whose access can be configured in the Users Settings. Set to false to require all users to login before accessing any wiki content. | false | | **defaultReadAccess** | yes | Should users that logged in using a social authentication provider have read-only access by default. | false | | **auth.local.enabled** | no | Enable the local authentication provider. | true | | **auth.google.enabled** | no | Enable the Google authentication provider | false | | **auth.google.clientId** | no | Google client ID that uniquely identify your app. | | | **auth.google.clientSecret** | no | Google client secret for your app. | | | **auth.microsoft.enabled** | no | Enable the Microsoft account authentication provider. | false | | **auth.microsoft.clientId** | no | Microsoft account client ID that uniquely identify your app. | | | **auth.microsoft.clientSecret** | no | Microsoft account client secret for your app. | | | **auth.facebook.enabled** | no | Enable the Facebook authentication provider. | false | | **auth.facebook.clientId** | no | Facebook client ID that uniquely identify your app. | | | **auth.facebook.clientSecret** | no | Facebook client secret for your app. | | | **auth.github.enabled** | no | Enable the GitHub authentication provider. | false | | **auth.github.clientId** | no | GitHub client ID that uniquely identify your app. | | | **auth.github.clientSecret** | no | GitHub client secret for your app. | | | **auth.slack.enabled** | no | Enable the Slack authentication provider. | false | | **auth.slack.clientId** | no | Facebook Slack ID that uniquely identify your app. | | | **auth.slack.clientSecret** | no | Facebook Slack secret for your app. | | | **auth.ldap.enabled** | no | Enable the LDAP / Active Directory authentication provider. | false | | **auth.ldap.url** | no | The URL of the LDAP / AD server. | | | **auth.ldap.bindDn** | no | The security object to use when connecting to the LDAP server, e.g. cn='root' | | | **auth.ldap.bindCredentials** | no | The password to use when connecting to the LDAP server. | | | **auth.ldap.searchBase** | no | The base LDAP directory where authentication should look for users. | | | **auth.ldap.searchFilter** | no | The expression to use when matching the username. Use `{{username}}` to specify the username provided by the user during login. | | | **auth.ldap.tlsEnabled** | no | Should TLS encryption be used when connecting to the LDAP server. | | | **auth.ldap.tlsCertPath** | no | The full local path to a certificate used to authenticate with the LDAP server. | | | **auth.azure.enabled** | no | Enable the Azure AD authentication provider. | false | | **auth.azure.clientId** | no | Azure AD ID that uniquely identify your app. | | | **auth.azure.clientSecret** | no | Azure AD secret for your app. | | | **auth.azure.resource** | no | Resource GUID used during authentication. | 00000002-0000-0000-c000-000000000000 | | **auth.azure.tenant** | no | Azure AD tenant hostname. Usually `SOMETHING.onmicrosoft.com` | | | **sessionSecret** | yes | A randomly generated string, used when encrypting sessions. 256-bit keys are usually a good choice. You can use this [key generator](http://randomkeygen.com/) to generate one. | | # Database | Property | Required | Description | Default Value | |---------------------|:--------:|--------------------------------------------------------------------------------------------------------------------------------------|:----------------:| | **db** | yes | The MongoDB-formatted [connection string](/wiki/install/database). | | # Git Repository Wiki.js works with pretty much any Git repository. See the [Git repository guide](/wiki/install/git) to learn how to get the necessary info from the most popular providers. | Property | Required | Description | Default Value | |---------------------|:--------:|--------------------------------------------------------------------------------------------------------------------------------------|:----------------:| | **git.url** | yes | The full URL to your Git repository where all content will be synced. | | | **git.branch** | yes | The branch of your Git repository to sync. | master | | **git.auth.type** | yes | The type of authentication to use when connecting to your Git repository. Valid values: `basic` or `ssh` | basic | | **git.auth.username** | no | The username to use when authenticating with your Git repository | | | **git.auth.password** | no | The password (basic), the OAuth token (oauth) or the private key passphrase (ssh) to use when authenticating with your Git repository | | | **git.auth.privateKey** | no | *(ssh only)* The full path to the private key (.pem) to use when authenticating with your Git repository | | | **git.auth.sslVerify** | no | *(ssh only)* Should the server check for a valid SSL certificate when connecting to your Git repository. | true | | **git.serverEmail** | yes | The default/fallback email address to use as the author when committing changes to your Git repository. | | | **git.showUserEmail** | yes | Should the commit author email be set to the current user. | true | # Features You can enable / disable specific optional features. | Property | Required | Description | Default Value | |---------------------|:--------:|--------------------------------------------------------------------------------------------------------------------------------------|:----------------:| | **features.mathjax** | no | Enable math equations processing (in TeX and MathML formats) and display them as SVG graphics. | true | # Logging By default, all logs are stored locally in the `/logs` directory. You can send logs to additional remote logging services: | Property | Required | Description | Default Value | |---------------------|:--------:|--------------------------------------------------------------------------------------------------------------------------------------|:----------------:| | **externalLogging.bugsnag** | no | Key to use for Bugsnag | | | **externalLogging.loggly.token** | no | Token to use for Loggly | | | **externalLogging.loggly.subdomain** | no | Subdomain to use for Loggly | | | **externalLogging.papertrail.host** | no | Host to use for Papertrail | | | **externalLogging.papertrail.port** | no | Port to use for Papertrail | | | **externalLogging.rollbar** | no | Key to use for Rollbar | | | **externalLogging.sentry** | no | Key to use for Sentry | | --- ## File: wiki/install/database.md {.pagelogo} # MongoDB MongoDB is a free and open-source cross-platform document-oriented database program. Classified as a NoSQL database program, MongoDB uses JSON-like documents with schemas. :information_source: **MongoDB** `3.2` **or later is required.** - [Official Website](https://www.mongodb.com/) - [Installation Guide](https://docs.mongodb.com/manual/administration/install-community/) It can safely be installed on the same server as Wiki.js. MongoDB is mainly used for users and content metadata, which is very light on server resources usage. Replica Set / Sharded Cluster installations are fully supported. Should you prefer on having a cloud provider host the MongoDB instance for you, here's a few examples: - [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) - [mLab](https://mlab.com/) - [Compose (IBM)](https://www.compose.com/mongodb) - [ObjectRocket (rackspace)](http://objectrocket.com/mongodb/) > :warning: **Cloud Provider Considerations** > > Make sure the MongoDB instance runs in the same datacenter (preferrably) or the same region. Connecting to instances located in another location will result in latency and poor performances! {.is-warning} # Connection String A MongoDB connection string is formatted as such: `mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]` Refer to the [official MongoDB documentation](https://docs.mongodb.com/manual/reference/connection-string/) for all the possible options. You can also use an **environment variable** containing the MongoDB connection string, e.g: `$(MONGO_URI)` # Examples **Using a local MongoDB instance (on the same server as Wiki.js):** `mongodb://localhost:27017/wiki` **A username/password protected instance on a single remote server:** `mongodb://username:password@remote.server.com:27017/wiki` **A username/password protected instance on a remote cluster:** `mongodb://username:password@first.server.com:27017,second.server.com:27017,third.server.com:27017/wiki`