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.yamltoHomestead.yaml. - Update
folders.mapinHomestead.yamlwith 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 installto 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 upto provision your vagrant machine. - In case the system didn't update your
/etc/hostsfile automatically:- Add the IP and domain defined at
Homestead.yamlto your local/etc/hostsfile.
- Add the IP and domain defined at
Once Homestead is set up, then install the website code itself:
- Run
homestead sshto ssh into the VM. cdinto the project folder in/home/vagrant/artic.edu.- Run
composer installinside the VM to ensure dependencies are installed. - Copy
.env.exampleas.envand update with your local settings (if necessary). - Run
php artisan key:generateto generate your application key. - Run
php artisan migrateto migrate the database schema. - Run
php artisan twill:superadminto 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.
20 Dec 24, 2022
1 Dec 3, 2021
669 Jan 5, 2023
0 Feb 14, 2022
8 Dec 19, 2022
2 Jan 3, 2022
6 Dec 8, 2022
2 Jan 10, 2022
2 Jul 4, 2022
279 Dec 28, 2022
3 Jul 29, 2022
5 Jun 1, 2023
1.7k Dec 24, 2022
6 Apr 5, 2022
2 Dec 11, 2022
1 Oct 16, 2021
6 Jul 20, 2022
1 Dec 8, 2021
13 Nov 27, 2022