How to create a DokuWiki Farm with Virtual Hosts

This screencast describes how to create a DokuWiki farm with virtual hosts, following these instructions: https://www.dokuwiki.org/farms

Tools used in this screencast:
* DokuWiki: https://www.dokuwiki.org/
* Uniform Server: http://www.uniformserver.com/
* Sublime Text Editor: http://www.sublimetext.com/

---

Closed Caption:

Hello and welcome to
my screencast about
How to create a DokuWiki farm
with virtual hosts
In here I will set up a local version
of a farm on my local Windows machine
so that it can later be transferred
to a hosted live server
I will basically only follow
what's described on
dokuwiki.org/farms
In here you will see that there are
two different kinds of setups
But in this screencast I will only cover
the virtual host based setup
Before we start
we need to make sure that
a standard DokuWiki installation
already exists
Which it does in here
And I've got it running on here
So, the first step
of creating a farm
is creating a farm directory
Which is as simple as that
It's just creating
a directory called 'farm'
Then you need to activate the farm
For that you need to go into your
'dokuwiki' directory
then its 'inc' directory
and there you will find
a file called
'preload.php.dist'
Rename that
to 'preload.php'
And open it
in a plain text editor
You can use Notepad
or anything else you prefer
I prefer Sublime
In here are
two lines you need to uncomment
The first line is
the definition of the farm directory
it needs to include the path
to the farm directory
Which is the directory
we just created
This one
So, we copy the path in here
And the second line you need
to uncomment
is this line, which includes
'farm.php'
which basically includes all the code
to make farms work
Save it
And we'll go to the next step
which is
adding an animal
An animal is one
child wiki instance
of which you can have
as many as you like
And you need to download
this zip file
[from dokuwiki.org/farms]
which is an animal directory template
You need to copy it into your farm directory
and unzip it
and copy and rename it
But
the way you need to rename it
is important
Let's assume
you own the domain
'example.com'
And you'd like to access your wiki
under the subdomain 'wiki.example.com'
I very often like to
distinguish between
the live wiki and the wiki
on your local machine
which I usually do with
prefixing this with 'dev.'
That will be the URL that
I'd like to access my wiki
on my local machine
The animal directory
needs to reflect that URL
I could simply paste this
and that would already work
But I'd like to make it work
so that
I can use it for the live wiki
as well
that's why I only name it
'wiki.example.com'
Which will work
for both instances
The next step, the fourth step
is adding required server settings
Before we can do that
there is one step more inbetween
which is not described on here
which is telling your computer
how to access this URL
You need to add this to your
'etc/hosts' file
You will find this file under
'C:\Windows\System32\drivers\etc\hosts'
With this file you basically
tell your computer
where to look
when it encounters this URL
And you just tell it to look
at your localhost with
this IP address for the localhost,
which is '127.0.0.1'
Save it
And now we can set up
a virtual host
If you're using XAMPP
you need to go to 'Config'
and 'Browse Apache'
which will open
the Apache folder
Go to 'conf/extra'
and there's a file called
'httpd-vhosts.conf'
Open this file
And in here you basically just
need to copy and paste
what's on here
[the farm documentation]
And change the values accordingly
This is just the most minimalistic
setup you need
This ['SeverName'] will be
'dev.wiki.example.com'
And the 'DocumentRoot'
is wherever your DokuWiki path is
So, it is in this case
'C:/xampp/htdocs/dokuwiki'
I actually use Uniform Server
And Uniform Server has a much nicer
way of doing this
You don't need to change
any config files
You just go to 'Server Configuration'
which opens a new window
There you go to 'Apache'
and 'Apache Vhosts'
And here you only need to add two things
'Document Root' and 'Server Name'
You just select the document root,
which is
the 'dokuwiki' folder
It's not the farm folder
and not any of the animals
but the 'dokuwiki' folder
And you add the server name
which was 'dev.wiki.example.com'
Click 'Confirm'
and 'Create Vhost'
And this will tell you
'For changes to take effect
restart Apache server'
which I will do right away
by stopping Apache
waiting a bit
and starting Apache
All [what] this did was basically
creating exactly the same entry
in the 'httpd-vhosts.conf'
And it should work now, let's try
Ta-daa! Our animal is ready, yay!
The next and final step
is to change the admin password
Because the animal template
that you downloaded
included one admin user with
one admin password
which is the same for everything
so you need to change it right away
you need to login with 'admin'
and the password is 'admin'
Go to the 'Admin' section
'User Manager'
and there you can click on the 'admin' user
Set a super secret password
And while you're here, you should also
change the email address
to your email address
or the admin's email address
Make it a bit nicer,
give it your real name
'Save Changes'
and you're done
You're now logged out again,
because that makes sense
you just changed your password
Login again, this time
with your super secret password
And while you're here, you can
change configurations as much as you like
For example this name 'Animal Wiki Title',
it sounds a bit weird
Let's change that
Go to 'Admin' and there you have
'Configuration Settings'
and there the first thing is the 'Wiki title'
Let's call it
'My Super Cool Wiki'
And it is your 'super cool wiki', yay
So, what do you need to do
to create a new animal?
Just repeat the last three steps!
Go to your farm directory
copy the animal template folder into something else
add a vhost
and you're basically done
Now that you can make all the changes
to your 'super cool wiki'
you will probably want to
upload it to a proper server
so that other people can see
your changes as well
There are only three things you
need to do for that
The first thing you need to do
is in the 'preload.php'...
You remember, we set the DokuWiki
farm directory in here?
But on the server it will
obviously be something else
In many standard Linux installations
it will be something like this
But especially on shared hosts you will
probably have something completely different
You might see that in your FTP client
you might see the real path
If you don't know the real path,
you can ask your hosting provider
Save that [file]
And when you then upload your code
just upload these two folders
and it's done
The standard DokuWiki installation
will already work
The animal will not quite work yet,
because there's one more step needed
You need to create the vhost
obviously also on the server
And the way to do that is basically
the same [as for the local setup]
Many web hosting services
have control panels
This is an example control panel
of something called 'cPanel',
which is quite popular
So, in here you have
basically
the same thing you saw me changing
on the Uniform Server interface
Which is, the 'Subdomain'
needs to be changed to
in our example 'wiki'
and the 'Document Root' needs
to go to the 'dokuwiki' path
Again, the confusing bit is,
not the path to the farm directory
or the animal directory
but to the 'dokuwiki' directory
And another popular one is 'Plesk'
Plesk looks very similar
you just add your 'Subdomain name'
and your 'Document root'
again, to the dokuwiki directory
And that's it
Then you can have fun
with your hundreds of animals
Happy farming!