The Makeability Lab is an HCI/Ubicomp research lab at the University of Washington directed by Professor Jon Froehlich. Founded in 2012 by Froehlich and students, the Makeability Lab focuses on designing and studying novel interactive experiences that cross between bits and atoms—the virtual and the physical—and back again to confront some of the world's greatest challenges in environmental sustainability, health and wellness, education, and universal accessibility.
This repository contains the Makeability Lab's website, which is written in Django (backend) and Bootstrap/Javascript (frontend).
Install Docker Desktop
Run > docker version
from terminal to ensure Docker is running
Clone this repository using git clone https://github.com/jonfroehlich/makeabilitylabwebsite.git
and navigate to the project home directory using the cd
command.
Edit the docker-compose.yml
file, commenting out the last two lines in the "volumes" section in the "website" service (there is a comment explaining which lines to comment out).
Build the docker images. Run docker build .
or docker build . -t <tag>
--the latter allows you to tag your build with a name (we recommend tagging it as makelab_image
for easy access). This step takes a while the first time (~2-3 min). If you don't add a tag to your build in step 3, you can look at the last line of the build that says Successfully built <tag>
to get your tag.
Running the container. Once the image has built, run docker-compose -f docker-compose-local-dev.yml up
, this will bring up both the postgres container for the database and the website containers. For future reference, running docker-compose up -d
will allow you to continue using the same terminal and none of the output messages will be displayed.
Create the superuser. In another terminal, navigate to the project home directory using the cd
command and open an interactive bash terminal in the website container using docker exec -it makeabilitylabwebsite_website_1 bash
. Once inside the bash terminal, run python manage.py createsuperuser
.
Open the development server in the web browser. At this point the development server should be running via step 4. You will find the website at localhost:8571
as specified in the docker-compose.yml
file.
Shutting down the server. In another terminal at the project home directory run docker-compose down
and wait for the containers to shut-down. Note without running this command, the development server will persist even when you close down the terminal, thus preventing you from using port 8571 for other purposes.
After running the docker-compose up
command, you will not need to rebuild or rerun the Docker container (unless you have made changes to docker-compose.yml). However, you will still need to refresh the webpage in order to see new updates.
git clone https://github.com/jonfroehlich/makeabilitylabwebsite.git
cd makeabilitylabwebsite/
docker build . -t makelab_image
docker-compose -f docker-compose-local-dev.yml up
You should then be able to visit the server at http://localhost:8571/
.
In new terminal (navigate to the project home directory)
docker exec -it makeabilitylabwebsite_website_1 bash
python manage.py createsuperuser
exit
On Windows, WSL2 provides an actual Linux kernel running within a lightweight VM, unlike the older WSL which tried to emulate a linux kernel within the Windows kernel—see Docker's official WSL2 overview. WSL2 offers faster compile times and is better supported by Docker.
Install Docker Desktop. Follow the official Docker Windows Install Guide.
Enter the Docker Dashboard and click the settings gear icon in the top right. From there, click the "General" tab and select the "Use the WSL 2 based engine" check box (this will be grayed out and pre-checked if you're running Windows Home).
Proceed by clicking Resources → WSL Integration and select your Linux VM of choice under "Enable integration with additional distros:". Here is some extra documentation from Docker that may help out with this process.
Open your Linux VM shell and navigate to where you would like to set up your Makeability Lab website repository.
Run git clone https://github.com/makeabilitylab/makeabilitylabwebsite.git
.
Run cd makeabilitylabwebsite
to change to he root website folder
Make sure to chmod 755 docker-entrypoint.sh
Make sure to chmod 777 media
(maybe 755 might be ok?)
You must also manually create some directories:
mkdir static
chmod -R 777 static/
mkdir website/migrations
chmod -R 777 website/
Build the docker images. Run docker build .
or docker build . -t <tag>
--the latter allows you to tag your build with a name (we recommend tagging it as makelab_image
for easy access). This step may take a while (~2-3 min). If you don't add an explicit tag to your build, you can look at the last line of the build that says Successfully built <tag>
to get your tag.
Running the container. Once the image has built, run docker-compose -f docker-compose-local-dev.yml up
, this will bring up both the PostgreSQL container for the database and the website containers.
At this point, you can visit the website at localhost:8571
as specified in the docker-compose.yml
file. However, to add content, you need to add an admin users. For this, follow the next step to create a "superuser."
Create the superuser. In another terminal, navigate to the project home directory using the cd
command and open an interactive bash terminal in the website container using docker exec -it makeabilitylabwebsite_website_1 bash
. If this fails, try docker exec -it makeabilitylabwebsite-website-1 bash
. Once inside the bash terminal, run python manage.py createsuperuser
and follow the instructions. Then you can visit localhost:8571/admin to add content.
It's also useful to create a mapping between your Linux filesystem in WSL2 and your Windows filesystem. For this, type Windows + R
to open the Run menu and type: \\wsl$
. Then, find the Linux installation you're using for the Makeability Lab website (e.g., Ubuntu-18.04) and right-click on that folder, then select Map Network Drive
and follow the on-screen instructions. By default, it will map to drive Z:
. So, you can open "This PC" or "My Computer" and see drive Z:
, which will be the Linux VM.
After following the above installation instructions, all future runs of the website can be accomplished by
makeabilitylabwebsite
directorydocker-compose up
Content must be added manually.
NOTE: If you haven't created a superuser yet, you will need to do so through terminal. Refer to Step 6 in the Docker Installation for more information.
localhost:8571/admin
in your browser. This will take you to the Django admin interface.TIP: Save time by only adding the content needed to fix the issue you are working on.
We have two UW servers hosting the ML website:
They have different PostgresSQL and file storage backends so adding content to -test will not affect the production server and vice versa.
The Makeability Lab website auto-deploys from GitHub to the department's Docker infrastructure using webhooks:
When we push code to github, the new code will auto-deploy to makeabilitylab-test. When we are ready to push changes to production, we need to do the following:
git tag <my version number>
git push --tags
This will cause that tag to deploy to production. To verify that the code has actually been pushed to production, view the buildlog.txt
here.
We will using semantic versioning when adding tags to push to production. The table below gives instructions for how semantic labeling works. More information is available here.
The current version number can be viewed here along with a history of all previous releases.
Code Status | Stage | Rule | Example # |
---|---|---|---|
First Release | New Product | Start with 1.0.0 | 1.0.0 |
Bug fixes, other minor changes | Patch release | Increment the third digit | 1.0.1 |
New Features that don't break existing features | Minor release | Increment the middle digit | 1.1.0 |
Changes that break backwards compatibility | Major release | Increment the first digit | 2.0.0 |
The production server was configured largely by UW CSE's Jason Howe. Note that settings.py reads in a config.ini file to configure a connection to the PostgreSQL database. This config.ini file is not in git (for obvious reasons as it contains secret keys and passwords). Thus, Jason has setup a "volume mount" for this file so that the production Docker session can read that file.
We have logging configured for both makeabilitylab-test.cs.washington.edu and makeabilitylab.cs.washington.edu.
recycle.cs.washington.edu
/cse/web/research/makelab/www-test
and view debug.log
/cse/web/research/makelab/www
and view debug.log
O:\cse\web\research\makelab
Because the log files are so large, use the tail
command to view the end of the log file. For example, tail -n 100 debug.log
will display the last 100 lines in the log file. You can also dump this to a new file: tail -n 100 debug.log > last100lines.log
You can also view buildlog.text
, httpd-access.log
, and httpd-error.log
at https://makeabilitylab-test.cs.washington.edu/logs/ and https://makeabilitylab.cs.washington.edu/logs/.
There are two types of Makeability Lab data:
All data/files uploaded to the Makeability Lab website via the admin interface (e.g., talks, publications) goes into the /media
folder, which is mapped to:
/cse/web/research/makelab/www
on production/cse/web/research/makelab/www-test
on testIf you want to look at uploaded content or view the debug.log
, you can SSH into recycle.cs.washington.edu
and cd to /cse/web/research/makelab/www
or /cse/web/research/makelab/www-test
, respectively.
The Makeability Lab website uses PostgreSQL on production, which is running on grabthar.cs.washington.edu. In the (extremely) rare instance that you need to access Postgres directly, you must do so via recycle.cs.washington.edu.
We use the following process for contributing code:
master
. The name of your branch should be descriptive and based off the issue that you are working on. (EX: if you were fixing this issue, an appropriate branch name would be adding-hover-to-landing-page
). Each branch should address one issue.Tasks that include changes to the user/admin interface should always include mockups. This is so we can collectively agree on how we want the site to look. A good example is here. Pull requests should also include before/after images, when applicable.
See our Troubleshooting wiki.