Mediawiki Setting Up Guide

MediaWiki Docker Setup Guide

This guide walks you through setting up MediaWiki using Docker and Dockhand. Follow the steps carefully, as specific paths are required for extensions and configuration to work correctly.

Getting Started

Before proceeding, make sure you have access to a Linux server or local machine with sudo privileges.

Installation Steps

1. Install Docker and Docker Compose

Ensure that Docker and Docker Compose are installed on your system. These tools are required to run MediaWiki and its supporting services in containers.

2. Set Up Dockhand

Dockhand provides a simple web-based interface for managing Docker stacks.

Run the following command in your terminal:

# Use matching paths with DATA_DIR 
docker run -d \
  --name dockhand \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/dockhand:/opt/dockhand \
  -e DATA_DIR=/opt/dockhand \
  fnsys/dockhand:latest

Once the container is running, open your browser and go to:

http://localhost:3000

You should now see the Dockhand web interface.

3. Create the MediaWiki Stack Directory

Next, create a dedicated directory on the Docker host for your MediaWiki stack.

This location is important because it will store your configuration files and extensions.

Run the following commands:

sudo mkdir -p /opt/stacks/mediawiki
sudo mkdir -p /opt/stacks/mediawiki/extensions
cd /opt/stacks/mediawiki

4. Create the Docker Compose File

Inside the /opt/stacks/mediawiki directory, create a Docker Compose file:

touch docker-compose.yml

This file will later contain the service definitions for MediaWiki, the database, and related components.

5. Edit the Docker Compose Configuration

Now you'll configure the services that will run your MediaWiki installation.

Open the file for editing:

nano docker-compose.yml

Paste the following configuration into the file:

services:
  mediawiki:
    image: mediawiki
    container_name: mediawiki
    restart: always
    ports:
      - "${MEDIAWIKI_PORT}:80"
    depends_on:
      - database
    volumes:
      - 230912_images:/var/www/html/images
      # EXTENSIONS: Mounts host folder to container
      - /opt/stacks/mediawiki/extensions:/var/www/html/extensions
      # CONFIG: Uncomment AFTER generating LocalSettings.php
      # - /opt/stacks/mediawiki/LocalSettings.php:/var/www/html/LocalSettings.php:ro

  database:
    image: mariadb
    container_name: mediawiki-db
    restart: always
    environment:
      MYSQL_DATABASE: "${MYSQL_DATABASE}"
      MYSQL_USER: "${MYSQL_USER}"
      MYSQL_PASSWORD: "${MYSQL_PASSWORD}"
      MYSQL_ROOT_PASSWORD: "${MYSQL_ROOT_PASSWORD}"
    volumes:
      - 230912_db:/var/lib/mysql

volumes:
  230912_images:
  230912_db:

Save and exit (press Ctrl + X, then Y, then Enter).

6. Create the Environment Variables File

The .env file stores sensitive information like passwords and port numbers. This keeps them separate from your main configuration.

While still in the /opt/stacks/mediawiki directory, create the environment file:

sudo touch .env

Open it for editing:

sudo nano .env

Paste the following configuration:

# MediaWiki
MEDIAWIKI_PORT=8595

# Database
DB_IMAGE=mariadb
DB_CONTAINER_NAME=mediawiki-db
MYSQL_DATABASE=my_wiki
MYSQL_USER=wikiuser
MYSQL_PASSWORD=your_secure_password
MYSQL_ROOT_PASSWORD=your_root_password

Note: Change the password values to something secure. Make sure DB_CONTAINER_NAME matches the container name in docker-compose.yml (in this case: mediawiki-db).

Save and exit.

7. Start the MediaWiki Containers

With your configuration files ready, start the Docker containers:

docker compose up -d

The -d flag runs the containers in the background (detached mode).

Initial MediaWiki Setup

8. Complete the Web Installation Wizard

Open your web browser and navigate to:

http://localhost:8595

Note: If you're setting this up on a remote server, replace localhost with your server's IP address.

Follow the on-screen setup wizard. When you reach the Database Settings page, enter these values:

• Database host: mediawiki-db
• Database name: my_wiki
• Database username: wikiuser
• Database password: your_secure_password

Note: These values should match what you set in the .env file in Step 6.

Complete the remaining setup steps, then download the LocalSettings.php file to your computer when prompted.

9. Move LocalSettings.php to the Server

Copy the downloaded configuration file from your local machine to the MediaWiki directory on your server:

sudo cp ~/Downloads/LocalSettings.php /opt/stacks/mediawiki/

Note: Adjust the path ~/Downloads/ if your file was saved to a different location.

Configuring Extensions

10. Extract Default Extensions (The "Magic Command")

MediaWiki comes with built-in extensions that need to be extracted to your host directory.

Step A: Extract Extensions

Run this command to copy all default extensions from the container to your host:

docker run --rm mediawiki tar -cC /var/www/html/extensions . | sudo tar -xC /opt/stacks/mediawiki/extensions

Step B: Fix File Permissions

Set the correct ownership and permissions so MediaWiki can use these extensions:

sudo chown -R 33:33 /opt/stacks/mediawiki/extensions
sudo chmod -R 755 /opt/stacks/mediawiki/extensions

Note: User ID 33 is the web server user (www-data) inside the container.

Step C: Add External Extensions (Optional)

To add extensions not included by default, download them to the extensions folder. For example, to add the Mermaid diagram extension:

cd /opt/stacks/mediawiki/extensions
git clone https://github.com/SemanticMediaWiki/Mermaid.git Mermaid

Note: Skip this step if you don't need the Mermaid extension or already have it installed.

Activating LocalSettings.php

11. Enable the LocalSettings Mount

Now that LocalSettings.php exists on your server, you need to mount it into the container.

Open the Docker Compose file again:

nano docker-compose.yml

Find this commented line in the mediawiki service section:

# - /opt/stacks/mediawiki/LocalSettings.php:/var/www/html/LocalSettings.php:ro

Remove the # to uncomment it:

- /opt/stacks/mediawiki/LocalSettings.php:/var/www/html/LocalSettings.php:ro

Save and exit.

12. Customize LocalSettings.php

Open the LocalSettings file for editing:

sudo nano /opt/stacks/mediawiki/LocalSettings.php

A. Set Your Custom Domain

Find the line that starts with $wgServer and update it with your actual domain or IP address:

$wgServer = "https://mediawiki.yourdomain.com";

Note: Use http:// if you haven't set up SSL/HTTPS yet. For local testing, use http://localhost:8595.

B. Add Permissions and Extensions

Scroll to the very bottom of the file and paste this configuration block:

/*-------------------------------------------
CUSTOM PERMISSIONS & EXTENSIONS
----------------------------------------- */

// 1. SECURITY: Prevent anonymous editing and account creation
$wgGroupPermissions['*']['edit'] = false;
$wgGroupPermissions['*']['createaccount'] = false;

// 2. BUNDLED EXTENSIONS
wfLoadExtension( 'WikiEditor' );
wfLoadExtension( 'VisualEditor' );
wfLoadExtension( 'CodeEditor' );
wfLoadExtension( 'SyntaxHighlight_GeSHi' ); # REQUIRED for Code Blocks
wfLoadExtension( 'Cite' );
wfLoadExtension( 'InputBox' );
wfLoadExtension( 'Scribunto' );
wfLoadExtension( 'AbuseFilter' );
wfLoadExtension( 'Gadgets' );
wfLoadExtension( 'ParserFunctions' );
// wfLoadExtension( 'Interwiki' ); # Moved to core in MediaWiki 1.44.0

// 3. EXTERNAL EXTENSIONS
wfLoadExtension( 'Mermaid' );

// 4. VISUALEDITOR CONFIGURATION
$wgDefaultUserOptions['visualeditor-enable'] = 1;
$wgVisualEditorParsoidForwardCookies = true;

// 5. LUA CONFIGURATION (Required for Scribunto)
$wgScribuntoDefaultEngine = 'luastandalone';

// 6. LOGIN SECURITY: Throttle login attempts
$wgRateLimits['user']['login'] = [ 5, 60 ];   // 5 attempts per minute
$wgRateLimits['ip']['login']   = [ 20, 300 ]; // 20 attempts per 5 minutes

Note: The Interwiki extension is commented out because its functionality was moved to MediaWiki core in version 1.44.0. If you're using an older version, uncomment this line.

Save and exit.

Finalizing the Installation

13. Update the Database Schema

After enabling extensions, update the MediaWiki database to recognize them:

docker exec -it mediawiki php maintenance/update.php --quick

14. Restart the Containers

Apply all changes by restarting the Docker containers:

docker compose up -d

Verification

Your MediaWiki installation should now be fully functional. Visit your wiki in a web browser to verify:

http://localhost:8595

You should see your wiki homepage with all extensions activated.

Troubleshooting

If you encounter issues:

• Check container logs:

docker compose logs -f

• Restart containers:

docker compose restart

• Verify file permissions:

ls -la /opt/stacks/mediawiki/