Here at Kinda Lame, we like self hosting things – being in control of our own software. There are too many cool projects out there to not take some time to play with and get your hands dirty. And one of the coolest projects out there is the ability to self-host MediaWiki software that lets you start your own wiki site (like Wikipedia).
No matter the topic, fan pages, fiction or putting together a family background website – you can relatively easily and quickly start up a wiki site and start documenting whatever you’d like. Even in small business and corporate environments there is value in having a central data store for human knowledge and a searchable and linkable wiki is a great way to get that done. It is the embodiment of the original world wide web dream – so let’s get started.
Docker is Lame
We love Docker at Kinda Lame! Simply put it’s the easiest way to try out software without hosing your Linux (or Windows) install. A lot of the packages we like to discuss here on Kinda Lame are maybe not always the most complicated but they require a set of dependencies installed on your base system. A fragile base system that might not get cleaned up should we decide to back out of our fun-time (maybe quarantine) project. Docker is just a cleaner way to try these things out – so we’re going to mark Docker as required for this project.
Again, I don’t want to cover how to install Docker – we have assumed thus far you’re even running Linux though you don’t have to be. That’s right, you can host a wiki, using MediaWiki, even in a Windows 10 Docker container. We suggest you start with their official instructions though I’ve covered how to install Docker in Debian 10 in another post about Mastodon.
But Slim How Do We Win?
Sure, you want to just get started. To do so I suggest taking a look at the official Docker image page for Mediawiki. This is going to be our basis for the setup we’re going to run. There are other options like Bitnami’s image – but why stray from the official images? We can customize it to our liking without taking a performance hit which will be key.
To do so we’ll just copy some files from the Docker container and mount them when we restart the image. Officially they have us do this with the LocalSettings.php file which will contain our settings for MediaWiki, we’ll just be taking things one step further.
Use Docker Compose with MediaWiki To Customize Your Wiki Experience
To get started we could just run Docker’s, uh, run command to fire up a MediaWiki instance and that would be perfectly fine. To do so we just need a simple commmand;
docker run --name mediawiki -p 80:80 -d mediawiki
Now we have MediaWiki running on port 80 and you can test this by visiting the localhost page:
But we want persistence, we want our wiki to live on so let’s not just fire it up and walk away. Let’s setup a production database with it using Mariadb, configure our maximum upload size so we can upload large images (and import lots of templates) and prepare ourselves to install as many extensions as we need. To do these things we need to run a second container, hack on php.ini and map the HTML files locally.
Getting started with Docker Compose
Docker has given us an example Docker Compose file to start with and we can use that as our basis, what I’ll show are my edits before copying some files from the container and running them locally. As always, find a place for your Compose files by creating a new directory (that resembles the container name you’ll use later – like “wiki”).
Notice and read the commented sections of the the docker-compose.yml file below – feel free to use this by copying and pasting the below into your own docker-compose file;
### Docker Compose Example for Kinda Lame ### Created October 2020 ### version: '3.2' services: web: ### ### We suggest using the LTS, long term support images ### image: mediawiki:lts ports: ### We are running the server behind NGINX which we ### recommend all users doing. And due to the need to ### login to the site we recommend running Certbot ### on your domain and putting the proxy behind ### an SSL certificate to keep your passwords safe! ### ### CHANGE THE PORT BELOW FROM 9999 TO YOUR DESIRED PORT - 9999:80 links: - database restart: unless-stopped volumes: - ./images:/var/www/html/images # - ./LocalSettings.php:/var/www/html/LocalSettings.php # - ./www:/var/www # - ./uploads.ini:/etc/php5/fpm/conf.d/uploads.ini:ro # - ./php:/usr/local/etc/php database: image: mariadb environment: MYSQL_DATABASE: 'wiki' MYSQL_USER: 'wikiuser234234' # # Generate a secure password and place it in the area below # MYSQL_PASSWORD: 'YOUR_SECURE_PASSWORD' MYSQL_RANDOM_ROOT_PASSWORD: 'yes' volumes: - ./database:/var/lib/mysql restart: unless-stopped
This will give you the basic setup to actually “install” MediaWiki and generate the LocalSettings.php file. Guidance on what to choose in the setup there is up to you and what you want to do with the site and varied. We’re going to focus on making sure we’ve captured the settings file and that Docker can load it on the next time we cycle the server.
First, let’s bring the server up for the first time.
We have assume two things;
- You have placed an Nginx Proxy in front of the exposed port
- You have run Certbot on this domain to generate the SSL certificate
If you have not, that’s okay – you’ll just be sending the administrator password in the clear for the first setup. Chances are this is okay and you can do that later. What’s the chance you’ll get your password sniped the only time you send it in the clear? Either way let’s bring up MediaWiki for the first time with Docker Compose;
sudo docker-compose up -d
After running through the setup (remember, by visiting the URL/PORT of the server you’re using) you’ll finish up with a page giving you the option to download the LocalSettings.php file. Do this, and stash it in the same directory you’ve started with, where docker-compose.yml is. Once the file is in place within the same folder you need to edit your docker-compose.yml file’s web section and change the volumes point to this file:
volumes: - ./images:/var/www/html/images #Uncomment the line below!!!! - ./LocalSettings.php:/var/www/html/LocalSettings.php # - ./mediawiki:/var/www # - ./php:/usr/local/etc/php
Now, before doing anything with your wiki let’s restart our Docker containers with the following one line command;
sudo docker-compose down && sudo docker-compose up -d
We’re running! You should now be able to revisit the main site and see the blank wiki. You’ve got some content to write! For fun head over to the Google Page Speed Insights tool and give it a run on your new site – you’ll be surprised how fast it renders.
Copying out Our Settings
We’re up and running and our site looks pretty decent out of the box. Here we can start writing content and adding pictures if we’d like. However we’ll find that out of the box we can’t upload images, or anything, over 2 MB. Why? Because this is the default settings in PHP – and we’re kind of stuck. The config for PHP is trapped inside the container.
We could simply log into the web container, find the file we need and make the updates we need to allow for larger uploads. However we want to be sure we don’t lose this setting when we upgrade the container and that’s easy enough.
Copy Out the PHP Settings Folder & Hack
What I discovered was that I couldn’t simply map the PHP etc folder (where the PHP settings are stored) first and fire up the container. I had to get it to run, download the files and then copy the files out – which makes sense, they didn’t exist when we started. Luckily this is easy because Docker gives us a way to copy files out of containers to our local file system. Remember each time we do these we’ll update our docker-compose volume mappings and restart the container by using “down” and “up” (see above one liner).
Oddly there is no default php.ini running in this container. We’ll copy out the examples, map them and create a new php.ini for us to use in our production setup – replacing the container name below;
sudo docker cp CONTAINER_NAME_FOR_WIKI_WEB:/usr/local/etc/php php
The above command should be run from the directory we’ve been working in, where our docker-compose.yml file is and where we are mapping things.
We’ll need to first move into the new php directory and copy the example php.ini-production file to the php.ini file we need and that the server will be looking for;
cd php && sudo cp php.ini-production php.ini
Now we have our php.ini file in place. We really just need to make a few edits here to change the max upload size. In our example I’m going to change it to 8 megabytes from 2 megabytes as this should be good enough for most images (we don’t want our site to be too big!). And for high resolution images we can always use the Wikimedia Commons existing artwork.
Open php.ini and search for the file uploads section and edit as follows, changing the upload_max_filesize from 2M to 8M;
;;;;;;;;;;;;;;;; ; File Uploads ; ;;;;;;;;;;;;;;;; ; Whether to allow HTTP file uploads. ; http://php.net/file-uploads file_uploads = On ; Temporary directory for HTTP uploaded files (will use system default if not ; specified). ; http://php.net/upload-tmp-dir ;upload_tmp_dir = ; Maximum allowed size for uploaded files. ; http://php.net/upload-max-filesize upload_max_filesize = 8M ; Maximum number of files that can be uploaded via a single request max_file_uploads = 20
There is one other change to make, and that’s to find the maximum post size in the php.ini file and change it also to 8M
; Maximum size of POST data that PHP will accept. ; Its value may be 0 to disable the limit. It is ignored if POST data reading ; is disabled through enable_post_data_reading. ; http://php.net/post-max-size post_max_size = 8M
Once our edits are in place we need to map them to the container again by editing docker-compose.yml and then the same volumes section we’ve edited in the web service:
volumes: - ./images:/var/www/html/images - ./LocalSettings.php:/var/www/html/LocalSettings.php # - ./mediawiki:/var/www #Uncomment the line below!!!! - ./php:/usr/local/etc/php
Now we are ready to reinitialize the docker containers by bringing them down and back up again, that command in one line is as follows;
sudo docker-compose down && sudo docker-compose up -d
Great – we have now set our maximum upload to 8 megabytes as opposed to the regular out of the box maximum of 2 MB. This is not only critical on uploading images as mentioned, but importing templates from Wikipedia or otherwise mass importing articles.
Mapping and Hacking the Core
So far we’re happy, we have a wiki running and we have increased our max upload amount. We have likely also enabled a series of out of the box extensions through the setup we ran through earlier in getting MediaWiki connected to the database and so forth. But what if we want to install other extensions?
Again, the files are all trapped inside the container.
This is easy enough, very much like we did before with the PHP settings. We’ll copy out the root directory of Apache inside the container, which exposes the extensions folders and others (again replacing with the web container name in your command);
sudo docker cp CONTAINER_NAME_FOR_WIKI_WEB:/var/www mediawiki
And once more we update docker-compose.yml to map to this direcory;
volumes: # - ./images:/var/www/html/images - ./LocalSettings.php:/var/www/html/LocalSettings.php #Uncomment the line below!!!! - ./mediawiki:/var/www - ./php:/usr/local/etc/php
Now we’re really rocking and rolling! We’ve created the docker container, we’ve edited it for our own world and we’ve extended it to allow for modifications. Now you can place extensions in the directory you copied out (under “mediawiki”, this is /var/www inside the container, the heart of MediaWiki) and initialize them with LocalSettings.php. You can also upload and import much larger files.
Great tutorial. Got my home wiki up and running at a fraction of the time with docker than I did with older 1.31 installs a few years back. Thanks!
Thanks, I’ve setup two but haven’t spent enough time building them out.
When I get to ‘Connect to Database’ on the initial setup, I get this “Cannot access the database: :real_connect(): (HY000/2002): Connection refused. Check the host, username and password and try again. If using “localhost” as the database host, try using “127.0.0.1” instead (or vice versa)” I did what is said and still get this error.
Justin – try using “database” as the hostname.
I get the same error as Justin — changing the hostname to “database” just updates the error to state: Access denied for user ‘root’@’192.168.80.3’ (using password: YES).
The MW installation DOES complete if I switch to SQLite, but then the rest of the tutorial breaks.
You’re having a password problem then – can you run a client outside of the setup and connect to the host and get in with the password?
Apologies, let me add – root may not be a good user, and that’s what the issue is. Recommend setting up another SQL user for this.
How can I do headless setup? I am on Ubuntu server terminal and I do not have web browser GUI access.
What is it you want to do – pre-fill the database with content?