Skip to content

Latest commit

 

History

History
100 lines (78 loc) · 6.81 KB

DEPLOYMENT.md

File metadata and controls

100 lines (78 loc) · 6.81 KB
Raw

DigitalOcean Deployment Instructions

Summary

This document is, essentially, a short guide to setting up a "droplet" on DigitalOcean to be used as a tool for deploying simple web applications. This is by no means a comprehensive guide, and you are encouraged to reach out to classmates, faculty, and TAs (through Slack, for example) with questions.

The majority of the information here will be presented in the form of bulleted lists, because we all know none of us actually read walls of text.

Most of this will happen in a terminal window, which is yet another reason to take some time to learn how to use the Unix shell.

Some terminology:

You're going to see the word "droplet" used a lot here. Digital ocean is in the business of hosting Virtual Private Servers (VPS), which they have decided to call "droplets." The term isn't terribly important, and for the most part just refers specifically to the VPSs hosted by DigitalOcean and all the features which that entails.

We will be using a tool called Docker to help with the deployment process. Docker is a tool for creating and running "containers." Containers allow a developer to package up an application with all of the parts it needs, such as libraries and other dependencies, and deploy it as one package. We will use Docker to separate our app into three containers. One for the Java server, one for hosting the client files, and one for the database.

  • A Docker image is the blueprint for a container. It contains the filesystem and instructions for what to execute.
    • Each part of the project, the client and server, have files called Dockerfile that instructs Docker how to create the image for each of them.
  • A Docker container is an instance of an image.
  • Compose is a tool for running multiple containers together and setting up storage and communication between them. We will be using the command docker-compose for much of the management of our containers.
    • The project has a docker-compose.yml file that instructs Docker Compose on how to run our server, client, and database containers together.

Step 1: Creating an account

  • Go to Digital Ocean.
  • You can create an account without adding billing information.
  • You cannot create any droplets without "activating" your account (by adding billing info).
  • You do get $100 of free credit for D.O. through the Github StudentPack. Be sure to redeem it.

Step 2: Creating a droplet

  • Go to this link. It should bring you to the Create Droplets page with the Docker marketplace image selected and the $5/month standard plan selected. If those are not selected, please select them.
  • Stick with the default datacenter / region (probably one of the U.S. options).
  • Scroll down and choose "One-time password." This will have them email you a temporary password for the root user.
  • You don't need to add block storage or backups.
  • Finally, only make one droplet and choose a name for it.
  • It will take a couple seconds to make the droplet.
  • You will then be able to see it on your Droplets page and get the IP for it.

Step 3: Setting up your droplet and running your project

  • SSH to your droplet by running ssh root@[my ip here] (using the IP of your droplet) and enter the password emailed to you.
  • It will ask you to set a new password for root. Enter the original password emailed to you and then set a new one.
    • This should be a good, secure password since it gives access to everything on your droplet and anyone can attempt to ssh into it. You may wish to use a random password generator for this.
    • You can change this password later with the passwd command.
  • git clone your repository
  • cd into the newly created directory
  • run ./setupdroplet.sh to go through the initial setup steps
    • It will ask you to agree to the Let's Encrypt Subscriber Agreement. You will need to answer yes or y to have HTTPS enabled.
    • If you answered yes in the last step it will ask for an email address, this is needed for HTTPS as well and will be used for any relevant alerts about your HTTPS certificate (you probably won't get any emails from them).
    • We are using a service called nip.io to give us the valid domains we need for HTTPS. The script will tell you the nip.io address your app will be hosted on.
  • To build and start your server, run docker-compose up -d
    • The -d means detached and you can then run docker-compose logs to see the output at any time.
    • To stop the containers, run docker-compose stop

Common tasks

Do all of these from within the base directory of the repo.

Resetting the database

To clear the current database and have it seeded again:

  • docker-compose down -v to stop and remove containers and volumes.
  • docker-compose up -d to build and start the containers again.

Updating the server or client code

If you have made changes and wish to update what is running on the server:

  • docker-compose down to stop and remove containers (if you want to also reset the database, use docker-compose down -v).
  • git pull to update the code.
  • docker-compose up --build -d to rebuild anything that has changed and start the containers.

Additional Docker Compose commands

  • docker-compose logs [service] will give you the logs of the specific service
    • For example, docker-compose logs server will give just the logs from the Java server.
    • docker-compose logs --follow will open the logs and follow their output so you can see new messages as they come. Exiting out of logs --follow does not stop the server containers.
  • docker-compose ps lists the running containers
  • docker-compose stop just stops all the containers, it does not remove anything.
  • docker-compose down stops the containers and removes them.
    • docker-compose down --rmi all removes all the images. It will then require rebuilding the images next time.
    • More options here
  • docker-compose build will build the images if things have changed in them

There are many more commands and options for docker-compose. They are all documented on the Docker Compose CLI reference.

Using a custom domain

If you have bought a domain for your project and would like to use it, set its DNS A record to the IP of your droplet. Stop and remove your containers with docker-compose down and then you can use nano or similar to edit the .env file and change APP_HOST to the domain you wish to use. After that use docker-compose up -d to start it up again.