vuthuan / twill-art

artic.edu

The code that runs the main website of the Art Institute of Chicago

This repository is all the code that runs artic.edu. With artworks in our collection, exhibitions, events, articles, and more, artic.edu is the main home for our museum's presence on the web. Take a look through our code, let us know if you have any questions, and feel free to use any portion of our code you like.

In production since 2018, our website is actively maintained by a team of developers, product managers, and system administrators at the Art Institute of Chicago. See our contributors for more details.

Overview

Our website is a Laravel website built with the Twill CMS. This repo includes all frontend, the Twill CMS, and an API.

Portions of the website rely heavily on our API. Check out a talk and a paper describing our API's architecture, and browse the code that powers our API.

Requirements

• PHP 7.3
• Node 8.17.0
• NPM 6.13.0
• PostgreSQL 11.*
• Homestead 12.*
• krpano 1.12.* (for virtual tour blocks)

Installing

Homestead

For local development, we run our website in a Homestead environment which provides all the software required to run the website.

• Rename Homestead.sample.yaml to Homestead.yaml.
• Update folders.map in Homestead.yaml with your local path to the website repository.
• If you have another vagrant machine running at the same IP as the one at the top of Homestead.yaml, change it.
• Run composer install to install composer dependencies. This step should typically be done inside the VM, but in order to get the VM running, you may need to install the dependencies from outside the VM.
• Run homestead up to provision your vagrant machine.
• In case the system didn't update your /etc/hosts file automatically:
  • Add the IP and domain defined at Homestead.yaml to your local /etc/hosts file.

Once Homestead is set up, then install the website code itself:

• Run homestead ssh to ssh into the VM.
• cd into the project folder in /home/vagrant/artic.edu.
• Run composer install inside the VM to ensure dependencies are installed.
• Copy .env.example as .env and update with your local settings (if necessary).
• Run php artisan key:generate to generate your application key.
• Run php artisan migrate to migrate the database schema.
• Run php artisan twill:superadmin to create a superadmin user.
• Build all necessary Twill assets: php artisan twill:build
• Access the frontend at http://{your_dev_domain}.
• Access the CMS at http://admin.{your_dev_domain}.

krpano

In order to use the virtual tour blocks, you will need to put the tour.js file in place from the krpano library. To do so, download krpano. Follow the instructions to install the package, and look for viewer/krpano.js among the files. Copy krpano.js to the public/virtual-tours directory in this project and rename it to tour.js.

Developing

Frontend

There are NPM packages required by the frontend of the website. To install them initially run:

npm ci
npm run build

For continuous work, run the following which runs as a watch command on locally changed JS and SCSS files:

npm run dev

We recommend using nvm or another node version manager to install exactly the node version listed in the requirements.

CMS

To compile all that is needed by the CMS, run:

php artisan twill:build

Style guide

Run this command to generate a style guide that will be served from http://{your_dev_domain}/styleguide

npm run toolkit

Upgrading Twill

Update the version of Twill in composer.json. Then to avoid composer running into memory issues, run:

php -d memory_limit=-1 `which composer` update area17/twill --with-dependencies --optimize-autoloader

There are usually local files that need updating to reflect the latest version. Look through the "Files changed" of a diff between versions in the Twill codebase: https://github.com/area17/twill/compare/2.3.0...2.4.0.

Once ready, run:

php artisan twill:update
php artisan twill:build

More documentation

We've developed detailed descriptions of a few key aspects of our website codebase:

• API models: How we've developed Eloquent-style model classes that are backed by our API
• Images: How to use images in the various types of models in our codebase

Testing

The website unit tests are configured to run with its own PostgreSQL database out of the box, see .env.testing. You'll need to create a database testing in your local DB environment and run the following before you run any tests:

php artisan migrate:fresh --env=testing

Contributing

We welcome your contributions. Please fork this repository and make your changes in a separate branch. To better understand how we organize our code, please review our version control guidelines.

# Clone the repo to your computer
git clone [email protected]:your-github-account/website.git

# Enter the folder that was created by the clone
cd website

# Install

# Start a feature branch
git checkout -b feature/good-short-description

# ... make some changes, commit your code

# Push your branch to GitHub
git push origin feature/good-short-description

Then on github.com, create a Pull Request to merge your changes into our develop branch.

This project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

We welcome bug reports and questions under GitHub's Issues. For other concerns, you can reach our engineering team at [email protected]

Acknowledgments

Thank you to everyone who has ever contributed to our website project! We appreciated all contributions, big and small. Learn more about who has worked on this project in our contributors doc.

Licensing

This project is licensed under the GNU Affero General Public License Version 3.