= How to setup and configure dokuwiki on AWS Lightsail =
**Summary**: This wiki page shows how I host this wiki using dokuwiki on an AWS lightsail instance. We will setup dokuwiki on AWS Lightsail, and configured it to use git as the backend for the pages and media. We will also setup a certificate using AWS Certificate Manager, and create a CloudFront distribution to serve the dokuwiki pages securely. \\
**Date**: 14 July 2025 \\
{{tag>dokuwiki aws git linux}}
Overall, the following techniques are used:
* Setup a lightsail instance in AWS
* How to configure apache & php for dokuwiki
* How to configure dokuwiki
* Use git as a version control mechanism for the wiki pages and media. And because the data is part of a larger repository we'll use sparse checkout
* Use Route53, certificate manager and cloudfront to setup a certificate for the wiki
* [[awslightsailcloudwatch|Use cloudwatch for monitoring]]
== Setup a Lightsail LAMP Instance ==
We need an instance to host dokiwki. We will use an AWS lightsail LAMP instance:
* In the AWS Console, open the Lightsail console -> Create instance
* Zone: Ireland (eu-west-1a)
* Apps + OS: LAMP (PHP 8)
* Version: 8.3.19
* Default SSH Key
* Network type: dual stack
* Size: 7$ per month; 1 GB Memory; 2 vCPUs Processing; 40 GB SSD Storage; 2 TB Transfer
* Instance Name: wiki.getshifting.com
By default, a lightsail instance has a builtin firewall that only allows SSH, HTTP and HTTPS for both IPv4 and IPv6.
Once the instance is available, we can access it from the console to start the configuration.
* Click on the prompt icon to open an terminal
* Set the hostname of the instance to wiki:
sudo vi /etc/hostname
sudo hostnamectl set-hostname wiki
* Configure a new user for ssh and sudo access:
sudo useradd -m sjoerd
sudo su - sjoerd
mkdir .ssh
chmod 700 .ssh/
cd .ssh
vi authorized_keys
# add the content of the public key and save the file
chmod 600 authorized_keys
exit
# setup sudo access
sudo usermod -a -G sudo sjoerd
sudo visudo
# Comment out the following line:
%sudo ALL=(ALL:ALL) ALL
# Uncomment the following line:
%sudo ALL=(ALL:ALL) NOPASSWD: ALL
=== Further setup the user ===
We can now login using ssh. For easy access, I've already set the domainname to {{{origin.getshifting.com}}} for the public IP in route53, and setup my ssh config file to use the private key for this host:
Host origin.getshifting.com wiki.getshifting.com wiki
HostName origin.getshifting.com
User sjoerd
IdentityFile C:\Users\sjoer\.ssh\id_ed25519_sjoerd
> I'm using origin.getshifting.com as the hostname for now, because this will be the origin for the cloudfront distribution, which will be used to serve the dokuwiki pages. The domain name will be set to wiki.getshifting.com later on.
Now we can login using ssh: {{{ssh origin.getshifting.com}}}
Set the default shell to bash:
sudo chsh -s /bin/bash sjoerd
To enhance our prompt and as we'll be working with git, we will add some git info to the prompy:
wget https://raw.githubusercontent.com/git/git/master/contrib/completion/git-prompt.sh
mv git-prompt.sh .git-prompt.sh
Now add the following lines to our users's .bashrc file:
# Use the git-prompt script to allow for git information in the prompt
# https://github.com/git/git/blob/master/contrib/completion/git-prompt.sh
. ~/.git-prompt.sh
# Uncomment the following line
force_color_prompt=yes
# Change the following line
#PS1='${debian_chroot:+($debian_chroot)}\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ '
PS1='${debian_chroot:+($debian_chroot)}\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[34m\]$(__git_ps1 " (%s)")\[\033[00m\]\$ '
=== Disable MariaDB ===
We won't need the MariaDB database, as we will be using git as the backend for dokuwiki, so we can disable it. Note that the Bitnami stack uses MariaDB instead of MySQL, so we will check for that first:
sjoerd@wiki:~$ test -d /opt/bitnami/mariadb && echo "MariaDB" || echo "MySQL"
MariaDB
sjoerd@wiki:~$ sudo /opt/bitnami/ctlscript.sh status mariadb
mariadb already running
sjoerd@wiki:~$ sudo /opt/bitnami/ctlscript.sh stop mariadb
Stopped mariadb
sjoerd@wiki:~$ sudo /opt/bitnami/ctlscript.sh status mariadb
mariadb not running
Now that MariaDB is stopped, we can disable it in the monit configuration, so that it won't be started again after a reboot:
sjoerd@wiki:/etc/monit/conf.d$ ls -al
total 24
drwxr-xr-x 2 root root 4096 Apr 3 16:27 .
drwxr-xr-x 3 root root 4096 Apr 3 16:27 ..
-rw-r--r-- 1 root root 323 Apr 3 16:27 apache.conf
-rw-r--r-- 1 root root 324 Apr 3 16:27 mariadb.conf
-rw-r--r-- 1 root root 317 Apr 3 16:27 php-fpm.conf
-rw-r--r-- 1 root root 334 Apr 3 16:27 varnish.conf.disabled
sjoerd@wiki:/etc/monit/conf.d$ sudo mv mariadb.conf mariadb.conf.disabled
sjoerd@wiki:/etc/monit/conf.d$ ls -al
total 24
drwxr-xr-x 2 root root 4096 Jul 10 05:50 .
drwxr-xr-x 3 root root 4096 Apr 3 16:27 ..
-rw-r--r-- 1 root root 323 Apr 3 16:27 apache.conf
-rw-r--r-- 1 root root 324 Apr 3 16:27 mariadb.conf.disabled
-rw-r--r-- 1 root root 317 Apr 3 16:27 php-fpm.conf
-rw-r--r-- 1 root root 334 Apr 3 16:27 varnish.conf.disabled
To make sure that the changes are applied, and test the result we can reboot the server: {{{sudo reboot}}}.
== Configure Apache & PHP ==
For the full background in configuring apache and php for dokuwiki, see the following links:
* [[https://www.dokuwiki.org/install:apache |dokuwiki apache installation]]
* [[https://www.dokuwiki.org/install:php |dokuwiki php installation]]
* [[https://www.dokuwiki.org/security |dokuwiki security]]
=== Apache ===
* Check for enabled apache modules: {{{apachectl -M}}}
* The rewrite module is enabled
* Enable htaccess overrides
* {{{sudo vi /opt/bitnami/apache/conf/httpd.conf}}} set the AllowOverride to All in the following section:
DocumentRoot "/opt/bitnami/apache/htdocs"
#
# Possible values for the Options directive are "None", "All",
# or any combination of:
# Indexes Includes FollowSymLinks SymLinksifOwnerMatch ExecCGI MultiViews
#
# Note that "MultiViews" must be named *explicitly* --- "Options All"
# doesn't give it to you.
#
# The Options directive is both complicated and important. Please see
# http://httpd.apache.org/docs/2.4/mod/core.html#options
# for more information.
#
Options Indexes FollowSymLinks
#
# AllowOverride controls what directives may be placed in .htaccess files.
# It can be "All", "None", or any combination of the keywords:
# AllowOverride FileInfo AuthConfig Limit
#
# AllowOverride None
AllowOverride All
#
# Controls who can get stuff from this server.
#
Require all granted
=== PHP ===
* Check enabled PHP modules: `php -m`
* all modules mentioned in the documentation are enabled
* Changed one setting in php.ini:
* {{{sudo vi /opt/bitnami/php/etc/php.ini}}}
* {{{max_input_vars = 1000}}}
== Configure dokuwiki ==
At this point a reboot, {{{sudo reboot}}} is always a good idea, before continuing and configuring dokuwiki:
* Download dokuwiki from [[https://download.dokuwiki.org/ | the dokuwiki download page]], select the latest stable version, and select only the English language pack.
* Copy the tarball to the instance using scp:
* {{{scp -r "C:\Users\sjoer\OneDrive - GetShifting\2025 05 Temp\dokuwiki" sjoerd@origin.getshifting.com:/home/sjoerd}}}
* Login to the instance to unpack the tarball to the correct location as the correct user::
* {{{sudo mv ./dokuwiki/dokuwiki-*.tgz /tmp}}}
* {{{sudo -u bitnami tar -xvf /tmp/dokuwiki-*.tgz -C /opt/bitnami/apache/htdocs}}}
* Now all the files have been extracted to {{{/opt/bitnami/apache/htdocs/dokuwiki}}}, which is one level too deep, so we need to move the files up one level. As we need to configure some more we'll do that as the bitnami user:
sudo su - bitnami
# Remove original index.html file
rm /opt/bitnami/apache/htdocs/index.html
# Move the files up one level
cd /opt/bitnami/apache/htdocs/dokuwiki
sudo mv * ../
# Also move hidden files
sudo mv .[^.]* ../
# Remove the dokuwiki directory
cd ..
sudo rm -rf dokuwiki
* Now we need to create a .htaccess file in the htdocs directory to configure dokuwiki:
* {{{vi /opt/bitnami/apache/htdocs/.htaccess}}}
* Add the following content to the file:
## You should disable Indexes and MultiViews either here or in the
## global config. Symlinks maybe needed for URL rewriting.
#Options -Indexes -MultiViews +FollowSymLinks
## make sure nobody gets the htaccess, README, COPYING or VERSION files
Require all denied
Order allow,deny
Deny from all
## Don't allow access to git directories
RedirectMatch 404 /\.git
## Uncomment these rules if you want to have nice URLs using
## $conf['userewrite'] = 1 - not needed for rewrite mode 2
RewriteEngine on
#
RewriteRule ^_media/(.*) lib/exe/fetch.php?media=$1 [QSA,L]
RewriteRule ^_detail/(.*) lib/exe/detail.php?media=$1 [QSA,L]
RewriteRule ^_export/([^/]+)/(.*) doku.php?do=export_$1&id=$2 [QSA,L]
RewriteRule ^$ doku.php [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule (.*) doku.php?id=$1 [QSA,L]
RewriteRule ^index.php$ doku.php
#
## Not all installations will require the following line. If you do,
## change "/dokuwiki" to the path to your dokuwiki directory relative
## to your document root.
#RewriteBase /dokuwiki
#
## If you enable DokuWikis XML-RPC interface, you should consider to
## restrict access to it over HTTPS only! Uncomment the following two
## rules if your server setup allows HTTPS.
#RewriteCond %{HTTPS} !=on
#RewriteRule ^lib/exe/xmlrpc.php$ https://%{SERVER_NAME}%{REQUEST_URI} [L,R=301]
* Now we need to make sure that the dokuwiki files are owned by the bitnami user and the daemon group, so that apache can access them:
# Set permissions to all files (including hidden ones) to bitnami and group daemon
sudo chown -R daemon:daemon *
sudo chown -R daemon:daemon .[^.]*
# Make the required directories writable for apache
sudo chmod -R g+w data/
sudo chmod -R g+w lib/
sudo chmod -R g+w conf/
* Reboot the instance again, so we know that all required processes have been restarted.
* Go to http://origin.getshifting.com/install.php, and start the dokuwiki installer.
* Install options:
* Wiki Name: wiki.getshifting.com
* Enable ACL
* Initial ACL policy: Public Wiki
* Disable 'Allow users to register themselves'
* License: GNU Free Documentation License
* Disable: Once a month, send anonymous usage data to the DokuWiki developers
> You should get a message saying that the installation was successful, and you can now login to the wiki, and delete the install.php file {{{sudo rm install.php}}}.
=== Test Dokuwiki ===
We can now do a few basic checks to verify everything is working in which we will also install the required dokuwiki plugins:
* Login as the admin user
* Follow the configuration steps as described in [[buildthissite]]
* Note that all the changes in wiki pages do not need to be made as the pages will be coming thorugh git in the next steps
* url rewrite: works
* sidebar: works
* installing plugins: works
* media manager: works
* favicon & logo: works
== Git ==
It is possible to use [[https://www.dokuwiki.org/plugin:gitbacked |git as the backend]] for dokuwiki pages and media, which allows us to get the best of both worlds. This enables me to use both git as well as the dokuwiki frontend to make changes to the content. But the content for the wiki is stored in a larger git repository, so we will use [[https://www.git-tower.com/learn/git/faq/git-sparse-checkout |sparse checkout]] to only checkout the dokuwiki pages and media directories.
> Note that git is already installed on the instance ({{{git --version}}}).
=== Daemon User ===
Let's start by creating new directories for the pages and media. Note that we first must setup the daemon user, as that's the user the apacher server is running under:
sudo mkdir /home/www
sudo chown daemon:daemon /home/www
# Set the home directory for the daemon user
sudo usermod -d /home/www daemon
# Set the shell for the daemon user to bash
sudo usermod -s /bin/bash daemon
# Check the home directory and shell for the daemon user
sudo cat /etc/passwd | grep daemon
# Output should be:
# daemon:x:1:1:daemon:/home/www:/bin/bash
Now we can logon as the daemon user: {{{sudo su daemon}}}. We will continue the git setup as the daemon user.
=== Create file structure ===
Follow these steps to create the file structure for the dokuwiki pages and media:
cd /opt/bitnami/apache/htdocs/
mkdir -p data/gitrepo/dokuwiki/media
mkdir -p data/gitrepo/dokuwiki/pages
# Add the content of the local.php file (see below) to the existing conf/local.php file
sudo vi conf/local.php
# Set the permissions again if required
sudo chown -R daemon:daemon *
sudo chown -R daemon:daemon .[^.]*
$conf['datadir'] = './data/gitrepo/dokuwiki/pages';
$conf['mediadir'] = './data/gitrepo/dokuwiki/media';
=== Configure git ===
Configure git on the lightsail instance:
# Configure git
cd /opt/bitnami/apache/htdocs/data/gitrepo
git config --global init.defaultBranch main
git config --global --add safe.directory /opt/bitnami/apache/htdocs/data/gitrepo
git config --global user.email "sjoerd@getshifting.com"
git config --global user.name "Sjoerd Hooft"
git config --global core.editor vi
git config --global http.sslVerify false
# Configure git authentication for push
PAT='see lastpass wiki.getshifting.com'
AUTH=$(echo -n ":$PAT" | openssl base64 | tr -d '\n')
REPO_URL="https://getshiftingcom@dev.azure.com/getshiftingcom/Documentation/_git/knowledge"
git config --global http.$REPO_URL.extraHeader "Authorization: Basic $AUTH"
# Check the git configuration
git config --global --list
# If something is wrong, you can edit the settings using: git config --global --edit
# Initialize the git repository
git init
# Add the remote repository
git remote add -f origin https://getshiftingcom@dev.azure.com/getshiftingcom/Documentation/_git/knowledge
# Enable sparse checkout
git sparse-checkout init
git sparse-checkout set dokuwiki/pages dokuwiki/media
git sparse-checkout list
dokuwiki/media
dokuwiki/pages
# Pull the latest changes from the remote repository
git pull origin main
=== Configure Dokuwiki for git backed pages ===
To make dokuwiki aware of working with git as the backend for the pages and media, we need to install the gitbacked plugin:
* Use the Extension Manager to install gitbacked:
* Admin -> Extension Manager -> Search and install ->
* Configure the gitbacked plugin:
* Admin -> Configuration Settings -> Gitbacked
* repoPath: /opt/bitnami/apache/htdocs/data/gitrepo
* Push active branch to remote origin after every commit: enabled
* Pull the remote git repository every "periodicMinutes" triggered by a http page request: enabled
* Update index of pages changed on pull: enabled
* Timespan (in minutes) between periodic pull requests: 60
=== Test git backed dokuwiki ===
* Make changes in git
* Check for the changes in the wiki (after 60 minutes)
* Make changes in dokuwiki
* Check for the changes in the git repository
=== Troubleshooting git backed dokuwiki ===
If you're working on the dokuwiki and the git backend at the same time you might run into problems with the git repository. The best advice is to not edit pages in dokuwiki and git at the same time, but if you've done so, you could run into any of the following issues:
* There is no tracking information for the current branch. Please specify which branch you want to merge with.
* Solution: {{{git branch --set-upstream-to=origin/main main}}}
* You have divergent branches and need to specify how to reconcile them.
* Solution: {{{git config --global pull.rebase true}}}
Always when you want to work with git on the server, follow the following steps:
cd /opt/bitnami/apache/htdocs/data/gitrepo
sudo su daemon
git status
# Check the remote repository
git remote -v
# Check git settings
git config --global --list
# Check the sparse checkout settings
git sparse-checkout list
# Pull the latest changes from the remote repository
git pull origin main
== Setup Route53, Certificate Manager and CloudFront ==
Now we want to make sure the wiki is securely accessible by using a certificate. Th easiest way is to use AWS Certificate Manager, Route53 and CloudFront to setup the certificate and the domain name.
=== Route 53 - origin.getshifting.com ===
This was already done when we created the instance for easy access to the instance, but this is how it's done. By now we will also use a fixed IPv4 address for the orgin.
* Go to the lightsail console and select the wiki.getshifting.com instance.
* Go to the Networking tab
* Below the current public IPv4 address, click on 'Attach static IP'
* Name the static IP: wikiStaticIP
* Now a new static IP will be assigned, which will be used for this instance even after a shutdown or reboot
Now we need to update the origin.getshifting.com A record in Route 53 to point to the new static IP address:
* In the route 53 console, go to the hosted zone for getshifting.com
* Select the origin.getshifting.com A record, and click on Edit
* Update the value to the new static IP address
=== Setup LetsEncrypt ===
Because cloudfront needs a certificate to be running on the local instance, we will create letsencrypt certificates using the bncert-tool that comes with the bitnami stack. This will also setup the cron job to automatically renew the certificate.
* Login to the instance and start the bncert-tool: {{{sudo /opt/bitnami/bncert-tool}}}. Use the following input for the prompts:
* Domain list []: origin.getshifting.com
* The following domains were not included: www.origin.getshifting.com. Do you want to add them? [Y/n]: n
* Enable HTTP to HTTPS redirection [Y/n]: n
* Do you agree to these changes? [Y/n]: Y
* E-mail address []: sjoerd@getshifting.com
* Do you agree to the Let's Encrypt Subscriber Agreement? [Y/n]: Y
Any changes and details can be reviewed in the following files:
Backup files:
* /opt/bitnami/apache/conf/httpd.conf.back.202506011407
* /opt/bitnami/apache/conf/bitnami/bitnami.conf.back.202506011407
* /opt/bitnami/apache/conf/bitnami/bitnami-ssl.conf.back.202506011407
Find more details in the log file:
/tmp/bncert-202506011407.log
> The certificate can be reviewed by going to https://origin.getshifting.com in a private browser tab and clicking on the lock icon in the address bar.
=== Setup Certificate Manager ===
Now we must create a certificate for the domain name wiki.getshifting.com, which will be used by cloudfront.
* Go to the AWS Certificate Manager console and make sure you are in the N. Virginia region (us-east-1)
* Request a new certificate with these settings:
* public
* wiki.getshifting.com
* DNS validation
* After creating -> click create DNS record in Amazon Route 53 -> Create Records
* Now wait for the validation
=== Create CloudFront Distribution ===
Now we can create a CloudFront distribution to serve the dokuwiki pages securely using the certificate we just created.
* Go to the CloudFront console annd click on Create distribution. Use the following settings:
* Origin: origin.getshifting.com
* Protocol: HTTPS only
* Viewer protocol policy: Redirect HTTP to HTTPS
* Alternate domain name: wiki.getshifting.com
* Custom SSL certificate: wiki.getshifting.com
* Default root object: index.php
* Description: wiki.getshifting.com
Wait for the distribution to be deployed, before continuing. After deployment, check the behavior tab. Dokuwiki works better if caching is only enabled for the media files, so we will change the default behavior (Default (*)) to not caching:
* From the behavior tab, select the Default (*) behavior and click on Edit
* Cache policy: CachingDisabled
> Note: With the latest dokuwiki version I kept having trouble with logging in. I had to create CloudFront Invalidations ({{{/*}}}) all the time to be able to log in. I removed all behaviors except for the default. After that it started working again.
Once you've saved the changes the distribution needs to be deployed again, which can take a few minutes. Note that, depending on already cached pages it might take a while for dokuwiki to work completely as expected.
=== Create Route 53 Alias Record ===
Change wiki a record to alias to point to cloudfront distribution
* In the Route 53 console, go to the hosted zone for getshifting.com
* Create a new record set with the following settings:
* Name: wiki.getshifting.com
* Type: A - IPv4 address
* Alias: Yes
* Alias target: Select the cloudfront distribution you just created
* Routing policy: Simple routing
== Backup ==
As all of the dokuwiki data is in the git repository, we only need a backup of the lightsail instance itself:
* From the lightsail console, go to the wiki.getshifting.com instance
* Click on the 'Snapshots' tab
* Click on 'Create snapshot'
* Name: wiki.getshifting.com-20250707
== Next Steps ==
The next step is to configure monitoring using AWS CloudWatch, which will allow us to monitor the instance and the dokuwiki pages. This will include setting up the CloudWatch agent, configuring log files, and creating a dashboard to visualize the metrics: [[awslightsailcloudwatch]].
== Useful Links ==
* [[https://docs.bitnami.com/aws/infrastructure/lamp/ |Bitnami package for LAMP for AWS Cloud]]
== Useful Command references ==
* [[https://systemd-service.readthedocs.io/en/latest/index.html Systemd-Service reference]]
* {{{systemctl enable iptables}}}
* {{{systemctl start iptables}}}
* {{{systemctl status iptables}}}
* {{{systemctl is-enabled iptables}}}
* {{{sudo systemctl restart sshd}}}
* {{{systemctl -l --type service --all}}}
* [[https://www.loggly.com/ultimate-guide/using-journalctl/ |Journalctl commands]]
* Per user: {{{journalctl _UID=1001 --since "1 hour ago"}}}
* List all enabled systmed units: {{{systemctl list-unit-files --state=enabled}}}
* Per systemd unit: {{{journalctl -u fail2ban.service --since "1 week ago"}}}
* Per command: {{{journalctl _COMM=sudo --since "1 hour ago"}}}
== Useful DokuWiki Directories ==
* {{{/opt/bitnami/apache/htdocs/data}}} - Contains the dokuwiki data
* {{{/opt/bitnami/apache/htdocs/lib/plugins}}} - Contains the dokuwiki plugins
* {{{/opt/bitnami/apache/htdocs/data/log/error}}} - Contains the dokuwiki error logs
== Known Issues ==
* The dokuwiki login doesn't work anymore, which is probably caused by the CloudFront distribution. This can be fixed by creating an invalidation ({{{/*}}}) for the CloudFront distribution, which will clear the cache and allow the login to work again.