Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Mediawiki on Heroku

Short url:

Unrelated update: my book is out! Debugging Your Brain is an applied psychology / self-help book

How to get set up with Mediawiki running on Heroku.

Create Git Repo

Fork (from the web interface)

(master worked fine for me, but you might want the last stable tag?)

git clone
heroku apps:create YOURAPPNAME

composer.lock setup

Mediawiki's repo doesn't have a composer.lock in it, and Heroku requires one. (I wish I knew more about why they didn't check that in?)

Before being able to generate a composer.lock, you may need to get php installed using brew see here (brew is for OSX). Packagist require you use a not-old version of openssl in your php, or else it won't let you download packages from it. Installing through brew gets a newer version of openssl bundled into your install of php.

Generate and add to the repo a composer.lock

brew install composer
composer update
git add -f composer.lock
git commit -m "add composer.lock"
git push heroku master

Configuring with ClearDB

Install an instance of ClearDB, either through the Heroku Dashboard or CLI. The free database isn't enough, you'll probably need the cheapest paid one ('punch', not 'ignite').

heroku addons:create cleardb:punch

Get the database information from the CLEARDB_DATABASE_URL ready to use soon mysql://USERNAME:PASSWORD@HOST/TABLENAME (and there is no table prefix)

heroku config

Now go to your deployed Heroku app, and follow the setup wizard. Put in the database information where requested.

Once you're done, you'll have to download LocalSettings.php and change some things before checking it into the repo. DO NOT check in LocalSettings.php with the passwords still in it. Instead, we'll use ENV vars.


Replace the ## Database settings sesction of LocalSettings.php with this (based on this):

## Database settings
$url = parse_url(getenv("CLEARDB_DATABASE_URL"));

$wgDBtype = "mysql";
$wgDBserver = $url["host"];
$wgDBname = substr($url["path"], 1);
$wgDBuser = $url["user"];
$wgDBpassword = $url["pass"];

Move the $wgSecretKey into an ENV var:

$wgSecretKey = getenv("SECRET_KEY");

Also move the $wgUpgradeKey into an ENV var:

$wgUpgradeKey = getenv("UPGRADE_KEY");

Now you can add, check in, push the new file "LocalSettings.php"

git add -f "LocalSettings.php"
git commit -m "add LocalSettings.php"
git push heroku master

Installing a Skin (Vector)

You can install the vector skin by adding it to the composer.json - add a line something like this (followed by composer update):

"mediawiki/vector-skin": "dev-wmf/1.30.0-wmf.2",

Then you'll have to add the skin explicitly to the bottom of LocalSettings.php like the instructions on the deployed site say to do (but what is the default skin for if it's not used??):

wfLoadSkin( 'Vector' );


An Example Setup

Compare it to mediawiki's repo to see the differences:


Inspiration taken from:

Copy link

AlessandroChecco commented Apr 23, 2017

This line should be removed now

echo "web: vendor/bin/heroku-hhvm-apache2" >> Procfile

Copy link

caseywatts commented May 29, 2017

ooh thanks @AlessandroChecco !

Copy link

caseywatts commented May 30, 2017

I ended up being able to remove a lot just now, and also found some more gotchas 🎉

Copy link

curtiscook commented Jun 7, 2017

you should move the secret keys for sessions & upgrades to environment parameters as well :)

Copy link

caseywatts commented Jun 15, 2017

Thanks @curtiscook! added that in, too :)

Copy link

lazaropj commented Jul 3, 2017

I could not install using the free database. I think it is necessary to have the plan paid.

Copy link

caseywatts commented Aug 17, 2017

ooh I had to use the paid one too actually - thanks for commenting that @lazaropj! !
Updated the instructions above to create a paid version cleardb:punch

Copy link

francisli commented Mar 24, 2018

Thanks for providing this great resource! I also configured SMTP mail support with the MailGun add-on by adding the following to LocalSettings.php:

$wgSMTP = array(
 'host'     => getenv("MAILGUN_SMTP_SERVER"), // could also be an IP address. Where the SMTP server is located
 'IDHost'   => getenv("MAILGUN_DOMAIN"),      // Generally this will be the domain name of your website (aka
 'port'     => getenv("MAILGUN_SMTP_PORT"),                 // Port to use when connecting to the SMTP server
 'auth'     => true,               // Should we use SMTP authentication (true or false)
 'username' => getenv("MAILGUN_SMTP_LOGIN"),     // Username to use for SMTP authentication (if being used)
 'password' => getenv("MAILGUN_SMTP_PASSWORD")       // Password to use for SMTP authentication (if being used)

As well as adding the necessary pear packages to the compose.json and the lockfile (run on the command line):

$ compose require pear/mail pear/mail_mime pear/mail_mime-decode pear/net_smtp pear/auth_sasl

Then commit your changes and push!

Also note that I was able to get up and running with JawsDB Maria db add-on on the free tier...

Copy link

francisli commented Mar 24, 2018

I'd recommend for Heroku deployments to set the cache directory:

$wgCacheDirectory = "/tmp";

Otherwise, it will default to storing/fetching localization cache data in the DB, which will run up your query and data count against limits (certainly, against the free tier of dbs).

I'll also be looking into submitting a patch back to MediaWiki for supporting SASL auth on memcached, which will allow using any of the memcache add-ons for object caching, which should also reduce load on the db...

Copy link

calebfergie commented Mar 15, 2019

Hi, thanks so much for this writeup! I'm a huge noob to php and wikis in general but wanted to drop a few notes in case someone else needs:

  1. Now go to your deployed Heroku app, and follow the setup wizard. - It took me a while you literally meant click open app in the heroku dashboard (or just navigate to the app in your browser) - the setup wizard is something you have to do on the wiki itself

  2. Small typo - Replace the ## Database settings sesction of LocalSettings.php with this sesction -> section

  3. Installing any other skin than these ones here requires a different methodology - I spent forever trying to install this one. I ended up succeeding by using git submodule add -f Tweeki (instead of git clone), and not changing anything in the composer.json file - though I'm not sure if that's a good practice... it just works.

Anyway thanks very much for this :)

Copy link

calebfergie commented Mar 29, 2019

Hi there, thanks again for this writeup. I am experiencing an issue with image retention on the wikis installed this way. Whenever I git push heroku master, previously uploaded image files disappear. I figure this is because the /images folder is wiped with every push.

The image file information is still stored in the clearDB, but always appears as a broken link. Do you have any suggestion about how I could handle this?

Others users will be uploading images as well, so I can't just add the images to my local instance of the MW.

Copy link

jlam55555 commented Aug 18, 2019

@calebfergie I haven't tried this (MediaWiki on Heroku) but I do know that Heroku has an ephemeral filesystem. I'm not sure how to do it with MediaWiki, but I believe the norm is to host files other platform, e.g., S3.

Copy link

calebfergie commented Aug 19, 2019

@jlam55555 yep, you're right -to work around this I ended up using an S3 bucket to store the images with the AWS Extension

You can see the full setup here.

Copy link

hxdsgnr commented Oct 21, 2019

Hello! I followed all the steps, but going to returns a blank screen :( I think it can be because the installation of the skin failed: I added both "mediawiki/vector-skin": "dev-wmf/1.30.0-wmf.2", and wfLoadSkin( 'Vector' ); in composer and LocalSettings, and the Vector folder in the skins directory, but when updating composer it didn't work. What could I have done wrong? Thank you :)

Copy link

calebfergie commented Oct 22, 2019

@luisparradev I had a similar issue - not sure if it will work for your setup, but you can try what I did above:

Copy link

xahon commented Dec 9, 2019

Is there a one-click deploy?

Copy link

ApopheniaPays commented Oct 21, 2020

Ok. Much as I appreciate the effort to help, the long and winding set of directions, followed by subsequent corrections and additions to those directions, and concluding with someone saying "All I get is a blank screen" and no decisive answer, then someone asking "Is there a one-click deploy" and no answer, does not look like a good use of time. However, I'm commenting to subscribe, in the hopes that someday somebody updates this with concise, confirmed working instructions.

Copy link

WAUthethird commented Mar 18, 2021

Please update this guide - brew installs Composer 2 by default which is incompatible with MediaWiki:

Copy link

WAUthethird commented Mar 19, 2021


Pages load so incredibly slow, and normal usage can result in the entire database crashing.
Switching to Amazon Aurora. This was horrible.

Copy link

reneklacan commented Dec 27, 2021

I ran into following issue while trying to follow instructions and deploying to heroku:

remote: Compressing source files... done.
remote: Building source:
remote: -----> Building on the Heroku-20 stack
remote: -----> Determining which buildpack to use for this app
remote:  !     Warning: Multiple default buildpacks reported the ability to handle this app. The first buildpack in the list below will be used.
remote: 			Detected buildpacks: PHP,Node.js
remote: 			See
remote: -----> PHP app detected
remote: -----> Bootstrapping...
remote: -----> Installing platform packages...
remote:  !     ERROR: Failed to install system packages!
remote:  !
remote:  !     Your platform requirements (for runtimes and extensions) could
remote:  !     not be resolved to an installable set of dependencies, or a
remote:  !     platform package repository was unreachable.
remote:  !
remote:  !     This usually means that you (or packages you are using) depend
remote:  !     on a combination of PHP versions and/or extensions that are
remote:  !     currently not available on Heroku.
remote:  !
remote:  !     The following is the full output from the installation attempt:
remote:  !
remote:  !     > You are using Composer 1 which is deprecated. You should upgrade to Composer 2, see
remote:  !     > Loading repositories with available runtimes and extensions
remote:  !     > Updating dependencies
remote:  !     > Your requirements could not be resolved to an installable set of packages.
remote:  !     >
remote:  !     >   Problem 1
remote:  !     >     - The requested package composer-plugin-api could not be found in any version, there may be a typo in the package name.
remote:  !     >
remote:  !
remote:  !     For reference, the following runtimes are currently available:
remote:  !
remote:  !     PHP:  8.1.1, 8.1.0, 8.0.14, 8.0.13, 8.0.12, 8.0.11, 8.0.10,
remote:  !     8.0.9, 8.0.8, 8.0.7, 8.0.6, 8.0.3, 8.0.2, 8.0.1, 8.0.0,
remote:  !     8.0.0RC4, 7.4.27, 7.4.26, 7.4.25, 7.4.24, 7.4.23, 7.4.22,
remote:  !     7.4.21, 7.4.20, 7.4.19, 7.4.16, 7.4.15, 7.4.14, 7.4.13,
remote:  !     7.4.12, 7.3.33, 7.3.32, 7.3.31, 7.3.30, 7.3.29, 7.3.28,
remote:  !     7.3.27, 7.3.26, 7.3.25, 7.3.24
remote:  !
remote:  !     Please verify that all requirements for runtime versions in
remote:  !     'composer.lock' are compatible with the list above, and ensure
remote:  !     all required extensions are available for the desired runtimes.
remote:  !
remote:  !     When choosing a PHP runtimes and extensions, please also ensure
remote:  !     they are available on your app's stack (heroku-20), and select
remote:  !     a different stack if needed after consulting the article below.
remote:  !
remote:  !     For a list of supported runtimes & extensions on Heroku, please
remote:  !     refer to:
remote:  !     Push rejected, failed to compile PHP app.
remote:  !     Push failed
remote: Verifying deploy...
remote: !	Push rejected to aoe4world-mediawiki.

It looks like issue might be that Heroku is trying to use composer 1 even though 2 should be supporter and it's failing, I only spent ~20 mins on trying to solve it with no success.

Copy link

klaraseitz commented Mar 21, 2022

To anyone still struggling:
I have written an updated tutorial on setting up mediaWiki on Heroku here

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment