deployment1Add my vote for this tag installation1Add my vote for this tag create new tag
, view all tags

How to Create an Amazon EC2 Instance (and Install TWiki)

2011-05-28 - 19:53:26 by PeterThoeny in General
What is TWiki?
A leading open source enterprise wiki and web application platform used by 50,000 small businesses, many Fortune 500 companies, and millions of people.
MOVED TO... Learn more.
I recently installed TWiki in the cloud, the Amazon Elastic Compute Cloud (EC2). I am sharing my installation experience for all to enjoy. EC2 is part of Amazon Web Services (AWS), allowing users to rent virtual computers on which to run software. EC2 allows scalable deployment of applications by providing a Web service through which a user can boot an Amazon Machine Image (AMI) to create a virtual machine, which Amazon calls an "instance", containing an operating system and any software desired. There are many ready made AMIs available, each can be instantiated with several options on memory, CPU and disk.

Let's look step by step on how to get a TWiki instance installed in the Amazon cloud. Part A of this article should be useful for anybody who wants to learn how to get started with EC2. Establishing a machine instance in the cloud is simply a point and click operation. Part B covers the TWiki installation, which are mostly manual tasks.

Part A: Create an AMI Instance in EC2

1. Sign up: Visit http://aws.amazon.com/ to sign up, it's free (but running an AMI costs money).

2. Select AMI: Decide on the AMI suitable for your needs. Visit http://aws.amazon.com/amis to browse and search the AMIs. TWiki runs best on Linux, so we search for a suitable Linux AMI. Amazon offers their own Linux distribution, they call it "Amazon Linux AMI". According to their website, their distribution "includes several packages that enable easy integration with AWS, including launch configuration tools and many popular AWS libraries and tools. Amazon Web Services also provides ongoing security and maintenance updates to all instances running the Amazon Linux AMI." So for TWiki we chose Amazon Linux AMI, Amazon EBS-Backed (64-bit), with AMI ID ami-8e1fece7.

3. Launch AMI instance: Now that we know which AMI to use we can instantiate it. Visit https://console.aws.amazon.com/, click on the "Amazon EC2" tab, then in the left navigation sidebar, click on "Instances". In the main window, click on the "Launch Instance" button to launch the Request Instance Wizard. First, search or browse for "Amazon Linux AMI, Amazon EBS-Backed (64-bit)" and select it.

In the next screens, enter the instance details. There are several instance types to chose from. For TWiki, the Micro type with 613 MB RAM is sufficient. Give the instance a name, in our case it is intra.

4. Create a public/private key pair: You can't ssh into an common Amazon instance (unless you built your own AMI). In order to establish a secure shell connection to the instance you need to create a public/private key pair. You can do that in the third step of the Request Instance Wizard. Create and download the key pair. It is important to store them in a safe and secure location. I moved examplekey.pem and examplekey.ppk into the .ssh directory below my OS-X home and changed the permission to 644 so that only the owner can read the file. You only need to create a key pair once, you can use it for all your instances. You can also download the key pair again if needed.

5. Review new instance: At the end of the Request Instance Wizard, review and confirm the new instance. After that you will see the instance in the "My Instances" table. In that table, click on the new instance to see details. Notice the Public DNS, something like ec2-x-x-x-x.compute-1.amazonaws.com - where x-x-x-x represents an IP address. This is the domain name we can use to access the new instance, aka server.

6. Login into the instance: Now that you have stored the key pair on your machine you can ssh into the sever without specifying a password. You need to login as user ec2-user:

ssh -i ~/.ssh/examplekey.pem ec2-user@ec2-x-x-x-x.compute-1.amazonaws.com

7. Install Apache and libraries: The Amazon Linux AMI is a minimal distribution. We first have to install the Apache webserver and other packages TWiki depends on. This is fairly simple because the Amazon Linux AMI uses yum. I found myself at home, this distribution looks identical to a Red Hat Enterprise distribution and CentOS distribution. Execute these commands to first gain root access, then install the required packages httpd, mod_ssl, perl-CGI and rcs:

$ sudo bash
# yum install httpd
# yum install mod_ssl
# yum install perl-CGI perl-Data-Dumper
# yum install rcs
# /sbin/service httpd start
Now we need to configure Apache. Edit /etc/httpd/conf/httpd.conf as root using your favorite editor such as vi or nano. Look for ServerAdmin and set this to a useful address, such as webmaster@example.com. Look for #ServerName www.example.com:80, and create a new line such as ServerName intra.example.com - later we will add a DNS setting for that domain. Changes done in /etc/httpd/conf/httpd.conf:
ServerAdmin webmaster@example.com

#ServerName www.example.com:80
ServerName intra.example.com
We also want to start Apache and configure Linux to start Apache automatically after a reboot:
# /sbin/service httpd start
# /sbin/chkconfig httpd on
# /sbin/chkconfig --list httpd
httpd          	0:off	1:off	2:on	3:on	4:on	5:on	6:off
The chkconfig --list httpd confirms that httpd will start after a reboot.

Some Linux versions use systemctl instead of chkconfig. If chkconfig does not work do this:

# systemctl enable httpd
# systemctl list-unit-files | grep httpd

Visit http://ec2-x-x-x-x.compute-1.amazonaws.com and you should see the default Apache welcome screen.

Part B: Install TWiki on AMI Instance

8. Configure Apache for TWiki: Visit http://twiki.org/cgi-bin/view/TWiki/ApacheConfigGenerator to generate the Apache conf file for TWiki based on your needs. Create /etc/httpd/conf.d/twiki.conf as root using your favorite editor such as vi or nano. Here is a sample twiki.conf file you could use, tailored for http, where all content is access restricted:

# Autogenerated httpd.conf file for TWiki.
# Generated at http://twiki.org/cgi-bin/view/TWiki/ApacheConfigGenerator

BrowserMatchNoCase ^$ blockAccess
ScriptAlias /do "/var/www/twiki/bin"
Alias /twiki/pub "/var/www/twiki/pub"

# Secure file attachments
RewriteEngine on
RewriteCond %{REQUEST_URI} !^/+twiki/+pub/+(TWiki|Main|Sandbox)/+.+
RewriteRule ^/+twiki/+pub/+(.*)$  /do/viewfile/$1 [L,PT]

<Directory "/var/www/twiki/bin">
    AllowOverride None
    Order Allow,Deny
    Allow from all
    Deny from env=blockAccess
    Options ExecCGI FollowSymLinks
    SetHandler cgi-script
    ErrorDocument 401 /html/login_error.html

<Directory "/var/www/twiki/pub">
    Options None
    AllowOverride None
    Order Allow,Deny
    Allow from all
    Deny from env=blockAccess
    AddType text/plain .shtml .php .php3 .phtml .phtm .pl .py .cgi
Now restart Apache to activate the new configure file:
=# /sbin/service httpd restart=

9. Download TWiki: Download the latest TWiki release from http://twiki.org/ to your local machine, then upload it to the Amazon instance. To upload the TWiki package, you can use secure copy in a similar way like ssh:

scp -i .ssh/examplekey.pem Download/TWiki-5.0.2.zip 'ec2-user@ec2-x-x-x-x.compute-1.amazonaws.com:~'
This copies the TWiki package to the home of the ec2-user user at /home/ec2-user.

10. Install TWiki: Login via ssh to the instance and perform the following steps to create the twiki directory, unpack the package, and set the ownership to the apache user:

$ sudo bash
# cd /var/www/
# mkdir twiki
# cd twiki/
# mv ~/TWiki-5.0.2.zip .
# unzip TWiki-5.0.2.zip
# chown -R apache.apache /var/www/twiki/
# cp -p bin/LocalLib.cfg.txt bin/LocalLib.cfg
The last cp command creates a file TWiki needs to find its libraries. Edit bin/LocalLib.cfg with your favorite editor such as vi or nano and set this:
$twikiLibPath = "/var/www/twiki/lib";

11. Configure TWiki: Run the TWiki configuration tool by pointing your browser to http://ec2-x-x-x-x.compute-1.amazonaws.com/do/configure. You are asked to set a password. Chose a good password, it is the administrator password who has super power in TWiki. Open up the "General path settings" section and set the following values:
  • {DefaultUrlHost} : http://intra.example.com
  • {PermittedRedirectHostUrls} : http://intra.example.com, http://ec2-x-x-x-x.compute-1.amazonaws.com
  • {ScriptUrlPath} : /do
  • {PubUrlPath} : /twiki/pub
  • {PubDir} : /var/www/twiki/pub
  • {TemplateDir} : /var/www/twiki/templates
  • {DataDir} : /var/www/twiki/data
  • {LocalesDir} : /var/www/twiki/locale
  • {WorkingDir} : /var/www/twiki/working
Later we will later add a DNS entry. Anticipating the setting, we already configure TWiki for the domain name we want to use, in our case intra.example.com. Proceed to save the changes. Then go back to the configuration. This time, click on the "Yes I have read the documentation" button to see the expert settings. Open up the "Security setup" section and set the following to require authentication for all content:
  • {AuthScripts} : attach, changes, edit, manage, oops, preview, rdiff, rdiffauth, register, rename, rest, save, search, upload, statistics, view, viewauth, viewfile
Open up the "Mail and Proxis" section and set this, taking an example for e-mail:
  • {WebMasterEmail} : twiki@example.com
  • {WebMasterName} : TWiki Administrator
  • {SMTP}{MAILHOST} : localhost
And save your changes.

12. Browse TWiki to finish configuration: Point your browser to http://ec2-x-x-x-x.compute-1.amazonaws.com/do/view/Main/WebHome. You are prompted to login. Login as user admin using the password you set in the TWiki configuration tool.

  1. Register yourself and other users: In the account pulldown, click on "Register user" and fill out the registration form.
  2. Add yourself and other administrators to the TWikiAdminGroup: In the TWiki home under the "Main web" pulldown, select "Groups" and click on the "TWikiAdminGroup". Edit the page and add a comma list of WikiNames to the GROUP bullet, such as:
    • Set GROUP = JimmyNeutron, DonaldDuck
  3. Logout and login with your WikiName. Visit and edit the TWikiAdminGroup topic to verify that you are an administrator.
  4. Change the site logo: Use a logo with transparent background, max size 200x40 pixels, and attach it to the TWikiPreferences page in the Main web. Edit that page and add this bullet to overload the default logo setting:
    • Set WIKILOGOIMG = %PUBURL%/Main/TWikiPreferences/example-logo.gif

13: Create a site homepage: The instance still shows the default Apache page. Create an index.html file in var/www/html/ with the content you like. It could be simply a redirect to the TWiki homepage (or login page for unauthenticated users). Example minimalistic index.html file that redirects:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 
 <meta http-equiv="refresh" content="0; url=/do/view/Main/WebHome" />
 <p>You are redirected to the <a href="/do/view/Main/WebHome">TWiki home</a>.</p>

14. Create a DNS entry: You probably want to access your TWiki site with a memorable domain name. Ask your webmaster to create a CNAME (name alias) for the new TWiki instance in the cloud. Example:

CNAME    intra    ec2-x-x-x-x.compute-1.amazonaws.com
This is a quick way to get your own domain name for your new TWiki. Keep in mind that the DNS name of the instance might change if you move or suspend the instance. You have to adjust the DNS entry each time if this happens. Amazon has so called Elastic IP Addresses to address this issue. You can programmatically map an Elastic IP Address to any virtual machine instance without a network administrator's help and without having to wait for DNS to propagate the new binding. Setting the DNS for an Elastic IP address is a bit different and out of scope of this article.

I hope this is helpful information. The first part of this article is not TWiki specific and should be useful for anybody who wants to get started with EC2. I am looking forward reading feedback.



Nice tutorial. It was very straight forward to follow and I got my twiki running on EC2 (and managed to setup Elastic IP on it!) I had some issue setting up security group though.. mainly because I didn't know that I can't change the security group name once I create my instance. Can you explain how much Amazon will charge to run TWiki on EC2?

-- Soichi Hayashi - 2011-06-02

I am glad it worked out for you Soichi-san. I do not know the monthly cost, but I think you can estimate using the EC2 cost calculator, http://calculator.s3.amazonaws.com/calc5.html. Are you a developer? I invite you to get involved with our community.

-- Peter Thoeny - 2011-06-02

You likely need more disk space, the default is about 1 GB - too small for most deployments.

Guide to resize the root partition on Linux in Amazon EC2: http://blog.linuxacademy.com/linux/resizing-root-partition-on-linux-in-amazon-ec2/

-- Peter Thoeny - 2013-09-10

If you run TWiki on EC2 you need to plan for backup. The cheapest way is to use Amazon S3 storage. Some instructions:

-- Peter Thoeny - 2013-09-10

Thanks for the excellent instructions! Just got my instance up and running. Note that I also needed to install the perl Data::Dumper and HTML::Entities packages. You may also want to more explicitly call out the apache restart at the end of step 8 (I missed it the first time and had to go back).

Thanks again!

-- Michael Morrissey - 2014-12-26

Thank you Michael. I fixed the doc accordingly.

-- Peter Thoeny - 2014-12-29

`chkconfig` only works for systems that use systemVinit. For systems that use systemd, you need `systemctl`.

# /sbin/chkconfig httpd on
# systemctl enable httpd

# /sbin/chkconfig --list httpd
# systemctl list-unit-files | grep httpd

see the following link for SysVinit to Systemd Cheatsheet

-- Arjun Sreedharan - 2015-04-30

Thank you Arjun. I updated the article accordingly.

-- Peter Thoeny - 2015-04-30


Edit | Attach | Watch | Print version | History: r6 < r5 < r4 < r3 < r2 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r6 - 2015-04-30 - PeterThoeny

Twitter Delicious Facebook Digg Google Bookmarks E-mail LinkedIn Reddit StumbleUpon    
  • Help
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2015 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.