Startup Instructions
Welcome!
Welcome to The Interventional Services Wiki Project! This page will walk you through the process of creating your very own wiki for your lab.
This startup guide will include all of the information needed to get your wiki running. It will also provide links to further information if you want to dive deeper into the subject matter.
The best advice we can give is: Don’t Panic! If something goes awry, it isn’t the end of the world. Here are some troubleshooting tips:
- if you get an error message, copy it and paste to a google search, there’s a good chance you will find an answer.
- Back up a few steps and make sure you followed them correctly. The command line has a shortcut: if you hit the up arrow on your keyboard, it will cycle through every command you have typed in since you logged in.
- If you feel all is lost, go to the Instance dashboard, select your instance, and from the actions menu, select Terminate instance. This will delete the instance. It may take a bit for it to disappear from the listing though.
- Launch a new instance and start over, it doesn’t cost anything as long as you only have one instance running at a time for the first year. You may have lost a bit of time, but you have gained experience…
Mini Tutorial
AWS Terminology
- Dashboard - A dashboard is the main page for the different services AWS provides. Just like you email program has a main page where all you emails are listed. When the instructions say to go to your instances, you would go to the EC2 service, and then select Instances. This may also be written like this:
AWS -> EC2 -> Instances
- AMI - Amazon Machine Image. An AMI is a “hard-drive” containing all of the software and data needed to run your wiki. these images are vetted by Amazon and available on the AWS marketplace. A Ubuntu Unix ami was used as a starting point for the wiki. You will go to the AWS marketplace to select the Interventional services wiki AMI.
- Instance - the instance is the “hard-drive“ and the “server“. In this case, it is a virtualized server that mimics the hardware that you choose to run the image. Once you have made all of the configurations to the instance, and launch it, then you will have a running server that you can connect to.
- IAM - Identity and Access Management. AWS includes some very powerful tools for controlling back-end access to your AWS account and instances. For example, the main AWS account that owns the wiki and domain names must include credit card and billing info. It might not be a good idea to have this information available to day-to-day staff. You can create another AWS account that can access the wiki Dashboard without having access to the billing module. This also makes it easy to manage access to any account in case of personnel changes.
- Key Pair - This is a cryptographic tool to keep access to your servers back end, called the command line, secure. You can think of it like a password, but it’s more like a paragraph. One part of the key, called the public key is stored on your server, and isn’t a secret, hence the name. The second part of the pair is the private key. You must keep this protected on your local computer. You will create one as part of the process of launching your first instance.
- Security Group - This is where you define your "firewall" settings. What ports (Channels) your server will communicate on, and whether it will talk to everybody, or only certain people. Like the Key Pair, you will define this before launching your first instance.
Server Terminology
- Command Line - A plain-text interface to the operating system of your computer. All computers have one, most people don't use them. A remote UNIX based server doesn't need one as it takes up a lot of memory and disk space. It is much easier to connect to the command line to control the server. Also referred to as the "Back end" of your server
- Web interface - Your web page. Sometimes known as the "Front end". The program that runs it is called Apache.
- SSH - Secure SHell. The command line program you will use to connect to your servers back-end. It is encrypted using the key pair mentioned above. You open a terminal program on your local computer to do this. There are also apps for your phone or iPad. And, as a last resort, AWS provides a terminal you can access through their website.
- Port - A virtual channel to separate internet communication into categories. Non-encrypted web traffic (http) is on port 80. Https, or encrypted web traffic, is on port 443. SSH connections happen on port 22.
- IP address(IP) - The electronic address of every device connected to a network. Phones, tablets, printers, your smart TV, everything. When you connect through your home WiFi, you have a different IP than when you connect through a cell connection. The IP is assigned to the device when it connects to the network. And the IP that the device has will not be the same IP that the server sees when you connect. It’s complicated…
Create an AWS account (Free)
The first step is to create an Amazon Web Services(AWS) account. If you already have one, that will work, but we encourage you to create an account solely for the wiki. A later tutorial will show you how to access the wiki from your AWS account. AWS requires a unique email address for a new account, so you may need to create one. Gmail works for this, or a dedicated account at your facility. Again, it is good practice to use a dedicated email for this and not a personal email account.
Launch your instance (Free)
After creating the AWS account, you will need to visit the EC2 service. This stands for Elastic Computing Cloud and manages your virtual servers. When it’s time to choose a domain name and link it to your server you will need to visit the Route 53 dashboard.
Before this step, select your AWS region. You will find this menu in the top-left corner of the screen next to your username. You don’t need to change the region, but choosing one closer to your location will help with response speeds. And if your instance is missing, check what region you are in, it’s likely you aren’t in the region you launched the instance in.
Once you are in EC2, click on instances. This is where you start, stop, and get info on all running instances for your selected region. Click on Launch Instance to start your server. The next page will require some info:
- Give it a name
- Pick an AMI. Do this by searching for “cath lab”.
- Instance type: we recommend t2.micro, its free for the first year, and more than enough to run the wiki.
- Choose or create your key pair
- If you are creating your key pair here, click create key pair and follow the instructions carefully. The private key should be saved on your computer as you will need it to access the command line interface. You can copy it to other devices should you need to access the command line from other locations or devices.
- Choose or create your security group
- To get started, allow SSH from anywhere, and HTTPS as well as HTTP from anywhere. However, we strongly suggest limiting SSH to specific IP addresses as soon as feasible. To allow only your current IP, you can choose “My IP” from the drop down when creating or editing the security group. You will most likely need to do this every time you go to the command line as IP addresses change depending on several factors.
- The storage default should be fine (8Gb)
Click Launch Instance at the bottom of the page, and go get a cup of coffee, as it will take 5-10 minutes for the server to boot up.
Configure your wiki
Connect to your instance
Go to AWS->EC2->Instances dashboard and look in the list of running instances. If you see one listed with Green Checkmarks by the Running status and 2/2 checks passed, congratulations, you have launched your server.
Now that you have a running server, you must do a few things to install MediaWiki and get it configured. AWS doesn’t allow this to be done for you as it requires choosing usernames and passwords to keep MediaWiki secure.
To do these things, you will connect to your server using a terminal program via SSH and the key-pair you created earlier.
If the policies of your facility don’t allow you to use these programs on work computers, you have a few options:
- Use a home computer
- Use a personal iPad or tablet
- Use the AWS console
Once you decide on a terminal program, familiarize yourself with using it to SSH into a server with a key-pair. They are all a little different and beyond the scope of this tutorial.
Click on the server listing to bring up details for the instance in the bottom panel. You are looking for the “Public IPv4 DNS” it will look something like:
ec2-##-###-##-###.us-west-2.compute.amazonaws.com
This is the temporary domain name assigned by AWS. Alternatively, you can use the IP address to connect.
Regardless of how your terminal program connects you will need the following:
- The server address or domain name from above
- The port 22 (always for SSH)
- The username - ubuntu (always)
- the path to your key-pair file
Make sure your security group allows SSH through port 22 from your computers IP address, or from everywhere before you connect!
Now connect to your server.
The command line
If you have made it here, congratulations! Welcome to the world of UNIX! When you type command here, you are interacting directly with the operating system of the computer. In the next sections, you will be typing commands to configure the back-end of the server for the wiki. Feel free to copy and paste the commands as shown in the code boxes:
Like this
Update the operating system
Even though we like to update the underlying AMI on a regular (~3 mos.) basis, updates and security patches are pushed constantly. This will also be covered in Server Maintenance, it is a good idea to make sure the operating system is up to date before you start installing things. Type the following:
sudo apt-get update
This will result in a lot of text flowing down the screen. This is normal. When it finishes, type:
sudo apt-get upgrade
This will be similar, and also ask you if you want to install, say ‘y’ again. It may tell you to reboot at the end of the process, if so type:
sudo reboot
Give the server 5-10 minutes to start back up and then re-connect.
Create MySQL user and database
Warning: If you use the placeholder values below, you will seriously compromise the security of your server!
Write down the database name, username, and password you choose as you will need it in the next section.
- From the command line launch MySQL with super user privileges.
sudo mysql
- Create the database. Replace wikidb with a database name for your installation.
CREATE DATABASE wikidb;
- Create a user for mediawiki to access the database. Replace wikiuser and strongpassword for this command. Don’t change localhost
CREATE USER 'wikiuser'@'localhost' IDENTIFIED BY 'strongpassword';
- Give the user rights to the database. Replace with the same values as above.
GRANT ALL PRIVILEGES ON wikidb.* TO 'wikiuser'@'localhost' WITH GRANT OPTION;
- Reset the privileges table
flush privileges;
- Exit MySQL
exit;
Install MediaWiki
Now you will access the web site directly. In the AWS Instances dashboard, click the open address link under the Public IPv4 heading. This will open your website in a new window. If it doesn’t, change the protocol in the url to http from https. Please note that you may get a warning that the site is not secure, proceed anyway and open the site. We will set up a self-signed https certificate at a later point. You will se a Ubuntu message page that the site is working, now add ‘/wiki’ to the end of the url to access the wiki. This will also change when we set up the domain name to point directly to the wiki.
- Click set up the wiki to begin.
- Pick your preferred language and localization. Click continue.
- This page checks to make sure everything is OK to install, you should have a green message saying it’s ok to install. Click continue at the bottom of the page.
- Connect to database. Here you will tell MediaWiki what you named the database and how to connect. Fill in the info you entered on the command line. If you didn’t write it down, switch to your terminal program as it should still be there on the screen.
- Database host is always localhost.
- Database prefix is not needed unless you are running multiple wikis from the same server.
- Fill in the username and password, then click continue.
- Click continue through this page
- Name your wiki and provide an Administrator account username and password. Best practice here is to call it something like admin or XYZadmin where XYZ is the short name of your department or facility. Keeping the Admin account generic is good policy. Individual users can have named accounts with appropriate access as needed.
- No need to put an email address here, unless you want to subscribe to the MediaWiki mailing list. You can choose not to share anonymous data about the wiki by unclicking the checkbox here.
- Make sure ask me more questions is selected, and click continue.
- Options page.
- Read through the options here and select the type of user rights that work for you. Our recommendation is Account creation required. Staff will be able to create accounts, and you can then lock down the wiki before you assign a domain name as bots will find you!
- No copyright info is necessary.
- Unless you wish to manage an email server, uncheck enable outbound email to close this section.
- Pick a skin for your wiki. Screenshots are available to compare.
- Under Extensions, only check Visual Editor.
- Images and uploads. Enable file uploads so it’s easy to put images on the wiki. Leave the rest blank and unchecked.
- Leave the rest of this page alone for now.
- Click continue to run the installer, and if it completes without errors, click Continue again.
- Follow the instructions on the installer page to install MediaWiki.
- Under extras, check only Visual Editor. The rest will be installed from the back end.
- When the installer is finished, download the LocalSettings.php file to your local computer.
- Return to the command line and create the LocalSettings.php file using the nano text editor:
sudo nano /var/www/html/wiki/LocalSettings.php
- Open the LocalSettings.php file you downloaded on your computer in the editor of your choice. Copy all the text.
- Switch back to the SSH program and paste this text into the nano editor.
- Make sure you are at the end of the file in nano.
- Use Ctrl-R to read in a file. It will ask for the location of the file. Paste in the following:
/var/www/html/wiki/SettingsExtras.php
- Use Ctrl-x to Save the file, answer ‘y’ to save the buffer, confirm the file name, and exit nano.
Add custom templates to MySQL
- Open MySQL and import theinterwikidata.sql. (Each of these is a separate command, do them one at a time)
sudo MySQL; use mywikidb; (Your database name) source /var/www/html/wiki/theinterwikidata.sql; exit;
This will overwrite all but the admin user with all the template data.
Update the data
- Update the database and Semantic Mediawiki with the data you just imported. (Again, run these one at a time)
php /var/www/html/wiki/maintenance/update.php (run this twice) php /var/www/html/wiki/extensions/SemanticMediaWiki/maintenance/rebuildData.php
Go back to the web interface and reload the page to confirm all is working. Proceed to fill in physicians and procedure data.
Create a domain name ($)
You will need to log-in to the Unix command-line interface(CLI) to make these changes. When you launched your instance from the AMI, you created a key pair. You will reference this key pair when using SSH to connect.
You can find a connection guide by clicking the connect button after selecting your instance from the list on your AWS EC2 dashboard.
Once you are connected to your CLI, you will need to edit the LocalSettings.php file.
First, change directory (cd) to the web server directory:
cd /var/www/html
Now, list all the files:
ls -al
This is your wiki code, the actual information in your pages will be stored in a database, more on that later.
Open a simple text editor and tell it to open the LocalSettings.php file with this command:
sudo nano LocalSettings.php
If you have never used a simple text editor, you may want to read up on it. Just Google "unix nano".
Let's change the name of your wiki first. Look for this section near the top:
$wgSitename = "YourWikiName"; $wgMetaNamespace = "YourWikiName";
Change these to the name of your wiki.
Next, a few lines down is this:
## The protocol and server name to use in fully-qualified URLs $wgServer = "http://00.00.00.00";
This must be changed to the IP address of your server. You can find this on your Instances page in your AWS console. Click on your instance, and the info will show up below it.
You can save the file at this point by using ctrl-x and entering a "y" for yes. At this point, your wiki should load if you point your web browser to the ip address. Please note you will have to specify a plain http connection, not https. Your browser will probably warn you the connection is unsecure, it's OK we will change this later to be secure.
As long as your wiki page loads, you're good so far! But we're not out of the woods yet, all the passwords and secret stuff needs to be changed as anyone who has this snapshot knows all of your passwords(not secure!)
Securing your server
Here is a list of things to change from the command line via SSH:
- MySQL (or MariaDB):
- There is no access to the mysql root user, so no need to change it.
- Create a new user (there isn't one at install)
- Grant all privileges on database "my_wiki" to new user
- edit LocalSettings "#Database Settings" section to reflect these changes
- Admin user password ("Admin12345" at install)
- Use the php script ChangePassword.php in the /maintenance directory to change the Admin password so you can log-in to the wiki.
- Change the secret key for the SecureHTML extension at the bottom of LocalSettings.php to a string of your own choosing
Open your Wiki for new users
- Edit LocalSettings.php
- Change the $wgGroupPermissions to allow account creation
Warning: This shouldn't be left on more than a couple days. Bots will find you!