Skip to content

Latest commit

 

History

History
161 lines (127 loc) · 10.6 KB

InstallationAndSetup.md

File metadata and controls

161 lines (127 loc) · 10.6 KB

Installation and Setup

This document is a guide on how to set up a web server to run the contents of this repository in a production environment.

If you are looking to set up the site locally, such as for development, please refer to the Local Development guide.

Table of Contents

  1. Before you begin
  2. Creating RDS Instance
    1. RDS Security
  3. Deploying to AWS
    1. Creating the Instance
    2. Domain Name
    3. Launching the Website
  4. Importing Data
  5. Post Installation

Before you begin

It is important to follow the steps in this document exactly as outlined, unless stated otherwise. The process for setting up this website involves Amazon Web Services (AWS), Docker, DNS servers, LetsEncrypt, and more. Ensure you have an AWS account.

You will need an email address to server as the webmaster. It will be used for administrative purposes on the site, such as the site's admin account, registering the domain name, etc. This does not need to be the same email address associated with your AWS account.

When dealing with Amazon Web Services, ensure that your location is the same across all platforms (EC2, RDS). The location should be displayed in the top right.

VERY IMPORTANT NOTE: In the startup.sh file, within the generate_ssl() function, Certbot is used to generate SSL certificates. If you are running this for development, you must make sure that the call to certbot includes the --dry-run flag. If you do not, you risk being rate limted (per 168 hours).

Creating RDS Instance

The first step is to use AWS RDS to create a MySQL database for the site.

Configuration will be dependent on your preferences and needs, this section will setup a simple, free RDS instance.

In AWS create an RDS instance with the following settings:

  • Create Database (Standard)
  • MySql 8.0.28 (default)
  • Burstable classes: db.t3.micro
  • General Purpose SSD
  • 20 GiB allocated
  • Enable storage autoscaling
  • 100 GiB maximum
  • Default VPC (make note of this ID, you will need it for the EC2 instance)
  • Public Access: No
  • VPC security groups: MySQL Access (if that isn't a group, just use default)
  • Password authentication
  • Additional Configuration > Initial database name: q2adb

Make sure to note down the database password and username (admin by default).

RDS Security:

  • To protect the site data, the database should have been configured so that only instances on the same VPC (i.e. the EC2 instance) can access it.
  • The EC2 instance should only have ports open for ssh (22), http (80), ssl (443), MySql (3306).
  • For the RDS instance, the only inbound port permitted should be MySql(3306). The source ip of the inbound rule should be the private ip of the EC2 instance.
    • You may need to come back and modify this after the Elastic IP has been generated. Just select the DB instance, then select its VPC security group, click Edit Inbound rules and set the source IP to the private IP of the EC2 instance.
  • This can be configured in the security groups of the EC2 and RDS instance.

Deploying to AWS

Now you can begin the process of launching the web server and setting up the website.

Creating EC2 Instance

The EC2 instance is the host of the web server and its details will depend entirely on the deployment's needs.

  1. Click "Launch Instance" or "Create an EC2 Instance" from AWS EC2 instance.
  2. Select Ubuntu 20.04 as the image.
  3. Select/create a key pair for ssh access.
    • Make sure you save the .pem key file, as these will be used to access the server later.
  4. Make sure the VPC is the same as the one used for the RDS instance.
  5. Select/create a network security group according to your deployment needs. For development, the following rules were used:
    • Type: HTTP, Protocol: TCP, Port Range: 80, Source: 0.0.0.0/0
    • Type: HTTPS, Protocol: TCP, Port Range: 443, Source: 0.0.0.0/0
    • Type: ssh, Protocol: TCP, Port Range: 22, Source: <Your IP>
    • Type: MYSQL/Aurora, Protocol: TCP, Port Range: 3306, Source: <Your IP>
  6. Expand the Advanced details section.
  7. Scroll down until you see a field marked User data.
  8. Paste the contents of the ec2_user_data.sh script into this field.
  9. Click Launch Instance.
  10. While waiting for the instance to boot (it may take a few minutes), click on it and copy its public IPv4 address.
  11. Connect to your instance through ssh using your preferred method. The command-line method will look like the following (you may need to sudo, depending on file permissions):
    • ssh -i </path/to/key.pem> <username>@<instance public IPv4>
    • <username> should be ubuntu if you chose an Ubuntu AMI.
  12. Once connected, ensure that the contents of this repository have been coped into /home/<username>/app.

Domain Name

You will need a static ("Elastic") IP address, a domain name, and the ability to create DNS records for the domain name.

  1. Navigate back to the AWS EC2 Console and search "Elastic IP" in the menu.
  2. Click "Allocate Elastic IP Address."
    • Note there is a charge for this if the address does not get associated with an EC2 instance.
  3. Select the IPv4 address pool option desired and allocate the address.
    • For development, we used "Amazon's pool of IPv4 addresses."
  4. After the IP was generated, click "Actions" and then "Associate" and associate the Elastic IP with the EC2 instance running the server.
  5. If you do not already have a domain name registered, register one before proceeding.
    • freenom was used for development, and the devevelopment domain name is supportsitetest.tk.
    • Used "freenom DNS" instead of custom name server.
  6. Configure the following DNS records for your domain:
    NAME TYPE TTL TARGET
    A 3600 <Elastic IP>
    www A 3600 <Elastic IP>

Launching the Website

Now you can launch the website itself.

  1. After the records have updated, reconnect to your EC2 instance through ssh.
  2. Once connected, run the following commands:
    • cd ~/app
    • sh startup.sh
  3. You may be prompted to provide information such as the AWS RDS credentials, website's domain name, and webmaster's email address.
  4. Once you have provided credentials, the docker-compose.yml file will be ran and the Docker containers will start.
  5. Open your web browser to http://<Elastic IP>.
  6. You will be prompted to create a "Super Administrator" account for the website. This is different than the administrator account for the database, but the same email address may be used.
  7. Once created, you will be brought to the site's homepage.
  8. Ensure that you can navigate to https://<Elastic IP> OR https://<Domain Name> and arrive at the same web page.

Importing Data

In order to transfer data to the site, you will need to have a local copy of it and ssh access to the EC2 instance. To mitigate errors when importing, ensure that the data loads properly on a local deployment.

  1. Get a dump of the desired data from your local machine.
    1. View your database from MySql Workbench.
    2. Go to Server > Data Export.
    3. Select the schema with the desired tables (if you don’t want to overwrite the tables storing site configuration do not select qa_options and qa_pages).
    4. Choose Export to Self-Contained File.
    5. Click Advanced Options and make sure set-gtid-purged - Add 'SET @@GLOBAL.GTID_PURGED' to the output is set to OFF.
    6. Start Export.
  2. Move the dump to the EC2 instance.
    1. Before you do this make sure you can SSH (secure shell) into the EC2 instance.
    2. Use scp to send the dump file to the EC2 instance:
      • scp -i </path/to/key.pem> <local dump file> <user>@<Elastic IP>:<destination of dump file>
      • Example: scp -i q2a_intern_key Dump20220701.sql [email protected]:~/dumps/Dump20220701.sql
  3. Import the data to the RDS instance.
    1. Now that the dump is on the EC2 instance we can import the data to RDS.
    2. Connect to the EC2 instance via ssh.
      • ssh -i </path/to/key.pem> <user>@<Elastic IP>
    3. Ensure mysql is installed
      • sudo apt install -y mysql-client-core-8.0
    4. (Optional) Verify your connection to the database works, for example: mysql -h q2a-db-test.cmnnis04whwr.us-east-1.rds.amazonaws.com -P 3306 -u admin -p
      • You can run \q to exit the MySQL connection
    5. Import the file into RDS, for example: mysql -h q2a-db-test.cmnnis04whwr.us-east-1.rds.amazonaws.com -P 3306 -u admin -p q2adb < Dump20220701.sql
      • If you encounter ERROR 1227 (42000) at line 18: Access denied; you need (at least one of) the SUPER, SYSTEM_VARIABLES_ADMIN or SESSION_VARIABLES_ADMIN privilege(s) for this operation, you may need to delete the following lines from your dump file:
        • --17: SET @MYSQLDUMP_TEMP_LOG_BIN = @@SESSION.SQL_LOG_BIN;
        • --18: SET @@SESSION.SQL_LOG_BIN= 0;
        • --24: SET @@GLOBAL.GTID_PURGED=/*!80000 '+'*/ '';
        • 1237: SET @@SESSION.SQL_LOG_BIN = @MYSQLDUMP_TEMP_LOG_BIN;

Post Installation

Once the site has been set up properly, you may want to perfom the following actions:

  • Check that you are always redirected to https://<Domain Name>/ when attempting to access the site through the Elastic IP or domain name using either HTTP or HTTPS.
  • Install the Dynamic Mentions plugin by copying the pupi-dm/ folder into public/qa-plugin/ in the web server.
    • This plugin is not included in this repository as, at the time of writing, the plugin is premium and not to be publicized.
  • Follow any steps in the Configuration document to ensure pages and plugins are setup properly.