teaching machines

CS 347: Webdev Blog

August 30, 2021 by Chris Johnson. Filed under fall-2021, specifications, webdev.

This semester you will document your learning of web development in a blog that you serve out via the Apache web server. Each week you will seek out articles or videos on HTML, CSS, JavaScript, or other web development topics and then write a short response to these materials. Use external source materials, not just the materials from your instructor.

Each blog post that you write must consist of the following:

• Two or more paragraphs summarizing what you learned. The words must be your own; do not steal others’ words.
• Sample code relevant to what you learned.
• Links or references to your sources.

Add a link to each new post in your blog’s index.html file. Make sure your instructor can see the links to all of your posts upon visiting http://blog.YOUR-DOMAIN-NAME.

If an entry meets all the requirements, you will receive 2 points. If you meet some, you will receive 1 point. If your blog post is not visible on Friday morning when your instructor reads through all posts, you will receive 0 points.

You are encouraged to write this blog and test it on your local machine and publish it to your web server when it’s ready. The remainder of this document describes how to secure a domain name and how to set up a standard workflow for developing and deploying websites that uses Visual Studio Code, Git, and Apache.

Install Git

Follow these directions to install Git or see if you already have it installed. Do not install GitHub Desktop. You only need the core Git, which is a set of command-line tools that you will run with the help of Visual Studio Code.

Create Local Repository

Follow these steps to set up a folder on your local machine in which you can construct, modify, and test your site without having to deal with an internet connection and a web server.

• Create an empty folder on your local computer. Name it blog perhaps.
• Open the folder in Visual Studio Code.
• Create a file named index.html and enter some simple HTML.
• In the Source Control panel—which you can reach via View / SCM or the button in the activity bar on the left—click Initialize Repository. A Git repository is essentially a database storing versions of files. You now have a local Git repository hidden in this directory in the .git folder. Your original folder is called the working directory. You must migrate changes from your working directory to the repository using two Git commands.
• The first command is to stage or add modified files to a staging area. Click the + icon next index.html to stage its changes.
• The second command is to commit all staged changed changes to the local repository. Enter a commit message in the text box and click the checkmark button labeled Commit at the top of the panel.

Your changes are now recorded in your local Git repository. The next step is to mirror those changes on a version of our repository hosted by a remote Git provider.

Create Remote Repository

Follow these steps to create a centralized version of your repository that you can access from your local machine and from your webserver.

• Create a new Git repository on GitHub, GitLab, Bitbucket, or some other Git provider of your choosing.
• Copy the URL of your repository (which probably has the form https://YOUR-GIT-PROVIDER/YOUR-GIT-PROVIDER-USERNAME/YOUR-REPOSITORY-NAME).
• Back in Visual Studio Code, click the ⋯ button at the top of the Source Control panel, and select Remote / Add Remote…
• Enter the URL of your remote repository.
• Name the remote connection origin.
• Push your local version of the repository up to the remote version. Click ⋯ and select Pull, Push / Push. Confirm the connection to an upstream branch.
• Reload the browser page showing your repository. You should see your index.html.

Clone on Droplet

Follow these steps on your droplet to pull down your repository from your Git provider.

• Log in to your droplet using your non-root account.
• While in your home directory, clone your remote repository using this command:

  git clone https://YOUR-GIT-PROVIDER/YOUR-GIT-PROVIDER-USERNAME/YOUR-REPOSITORY-NAME

• Confirm that index.html is in the directory with these commands:

  cd YOUR-REPOSITORY-NAME
  ls

• Print the working directory by running pwd. The path you will see is /home/YOUR-DROPLET-USERNAME/YOUR-REPOSITORY-NAME. This path is important. You will need it later when configuring Apache.

Domain Name

You could share your blog with the world by giving out your IP address. Others could visit http://YOUR-IP-ADDRESS in their browser. But that’s gross. Instead, you will give your web server a mnemonic domain name. Follow these steps to get a free domain name that you will use to identify your Digital Ocean droplet.

• Visit the GitHub Student Developer Pack.
• Under the Namecheap section, claim your 1-year domain name registration by connecting your GitHub account to a Namecheap account. Note that this is the bottom link, not the top one about SSL.
• Choose a domain name. Pick something meaningful to you as an individual. It need not and probably should not be tied to any particular project, as each of your projects will be served out as a subdomain of this domain name. For example, your blog will be accessed via http://blog.YOUR-DOMAIN-NAME and your static site will be served out as http://project1.YOUR-DOMAIN-NAME.
• Find your domain under Domain List and click Manage.
• Under Advanced DNS, remove any A records whose IP address starts with 185. These are inserted automatically to point to GitHub Pages. You don’t want that.
• Click Add New Record and add an A Record. For host, enter the wildcard *. For the IP address, enter your droplet’s IP address. Save the record. This will make all subdomain URLs point to your server.
• For good measure, add another A Record. For host, enter @. For the IP address, enter your droplet’s IP address. Save the record. This record will make the URL http://YOUR-DOMAIN-NAME, which has no subdomain, point to your server.
• Let a few minutes elapse and then visit http://YOUR-DOMAIN-NAME in your web browser. You should see your Apache test page. Right now your domain name is very general and goes to any virtual host that Apache knows about.

Configure Apache

Follow these steps on your droplet in order to share the working directory of your clone with the world via the Apache web server.

• Create a configuration file that tells Apache about your blog. You will need to create a file using a command-line text editor. Two of the most popular text editors are vi and emacs. You are encouraged to learn one of them. You may be intimidated or disgusted by the prospect of command-line editing. It’s okay to feel that way. However, the benefits of knowing one of these editors outweigh the costs. Create the file with one of the following commands:

  sudo vi /etc/apache2/sites-available/blog.conf
  sudo emacs /etc/apache2/sites-available/blog.conf

  Other editors are fine too.
• Add the following text to the file, replacing YOUR-REPOSITORY-NAME and YOUR-DROPLET-USERNAME with their actual values:

  <VirtualHost *:80>
    ServerAdmin webmaster@localhost
    ServerName blog.YOUR-DOMAIN-NAME
    DocumentRoot /home/YOUR-DROPLET-USERNAME/YOUR-REPOSITORY-NAME
  
    # Allow access to all files.
    <Directory /home/YOUR-DROPLET-USERNAME/YOUR-REPOSITORY-NAME>
      Require all granted
    </Directory>
  
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
  </VirtualHost>
  

  Double-check your paths for the DocumentRoot and Directory directives. They should point to valid paths in your file system. If you instructor is the one who identifies your typos, he will threaten that you will have to pay for a month of his web hosting costs. Save the file and exit the editor.
• Enable the site and restart Apache with these commands:

  sudo a2ensite blog
  sudo service apache2 restart

• Visit http://blog.YOUR-DOMAIN-NAME in a browser and marvel at your accomplishment. Your website is live! Maybe?
• If you see a Forbidden error, give the directory and all of its children (recursive with -R) permissions so that the Apache server, which runs as a different user, can read them. You add read (r) and execute (capital X) permissions to the group (g) and others (o) with this command:

  chmod -R go+rX ~/YOUR-REPOSITORY-NAME

  If you still see a Forbidden error, double-check your paths in your blog.conf file. Run pwd from your working directory to get the full path that you should be using. If you make changes to blog.conf, restart Apache.
• Send your instructor a link to your blog in a direct message in Slack.

Weekly Workflow

Many of the steps above are needed only for your initial one-time setup. Each week, follow this much simpler workflow:

• Open your blog’s working directory in Visual Studio Code.
• Pull down any changes that you’ve pushed from other computers. Click ⋯ at the top of the Source Control panel and select Pull, Push / Pull. If you aren’t making changes on any other computers, then you can skip this step.
• Add a new HTML page for the week’s entry, and insert and test your desired content.
• Add a link to your new page in index.html.
• Stage and commit the changes.
• Push the commits from your local machine to your Git provider. This step is easy to forget because there’s no UI telling you that your local and remote repositories are not in sync. Do not forget.
• Log in to your droplet and run the following commands:

  cd YOUR-REPOSITORY-NAME
  git pull

• Re-run the chmod command to ensure all files are readable.
• Verify that your new entry is visible by visiting your site in a browser.