Deploy Your Project
Learn various methods to preview & deploy your project online
A Quire site is designed to be hosted on virtually any web server, either one your institution already runs, or a new server from the hosting service of your choice. You do not need any special back-end setup. If you plan to include PDF and e-book files as part of you published project, it’s important that you start by following the directions in the Output Your Project section of the documentation before proceeding.
Basic Deploy
When hosting a Quire site, you will typically follow these steps:
- Update the
baseURL
inconfig/site.yml
to match the URL where the site will ultimately be hosted. - Create the HTML files for your project by running
quire site
in your command-line shell. The files will be built into your project’ssite
folder along with all the necessary static assets like image files, stylesheets and script files. Thesite
file will be updated and overwritten each time you runquire site
. - Upload the contents of the
site
folder to your web host based on the directions they provide.
If you do not already have a web server or hosting plan, we recommend using either Netlify or GitHub Pages.
- Netlify’s “Continuous Deployment” option and Github Pages require a basic understanding of how to create a repository, and commit and merge changes changes. If you are new to GitHub, we recommend starting with GitHub Docs to learn by topic or by visiting the Project Management with GitHub section of our documentation. We also encourage you to check out Coding Train’s video series Git and Github for Poets.
Netlify
Netlify enables you to create a quick preview site by using your project’s site
files or by connecting it with your Github account to generate a shareable preview site that automatically updates every time you push changes to GitHub. (Please note, while we use GitHub and reference it throughout our documentation, you can also link Netlify to your GitLab or BitBucket account.) You can also use Netlify to host your final project when it’s ready to publish.
To learn more about connecting domains, build configuration, private submodules, and using Git Large File Storage with Netlify, see Additional Netlify Tips.
To get started, sign up for a Netlify account and, optionally, connect it with your GitHub account.
- If you try the GitHub Pages option before trying Netlify, undo the changes you made to
themes/default/webpack/webpack.config.prod.js
before proceeding. Otherwise, deploy will not work.
Manual Deployment with Netlify
Manual deploy is ideal if you have a small site or want to run a quick preview. You can also use this option without needing a GitHub account. However, each time you make an update, you will need to go through the process of rebuilding the site, compressing files, and reuploading them to Netlify, which may be burdensome if you have a lot of images or larger files. For continuous deployment please see Continuous Deployment with Netlify.
When you are ready to launch your project, run the
quire site
command in your command-line shell.Navigate to your project in your home directory and compress the
site
folder.Go to Netlify Drop: https://app.netlify.com/drop. Make sure you are logged in to your account and then drag-and-drop your compressed
site
folder into the indicated area.You will be given a default URL to preview your project. Rename this URL by navigating to “Site settings” and changing the site name. (You also have the option to buy a domain or set-up a domain you already own.)
If you make further edits to your project and would like to preview them you will need to repeat this process.
Delete the old compressed
site
folder.Run
quire site
again (your files will be automatically overwritten.)Compress the newly updated
site
folder.In Netlify, navigate to “Deploys” at the top of the page. You will see a blank space that reads, “Need to update your site.” Simply drag-and-drop your new compressed
site
folder here and your link will be automatically updated.
- One downside to manual deploys is that they can sometimes get stuck while uploading. To ensure a reliable deploy, use this option for Quire sites under 50MB and avoid individual files over 10MB. It’s also recommended that you use the latest version of the Chrome browser. For more tips visit the Netlify Support Forum.
Continuous Deployment with Netlify
By keeping your project files on GitHub and linking them directly to your Netlify account, any time you merge changes in Github, your preview link will be automatically updated. This process requires a few extra steps to get set-up, but will save time in the long run.
If you haven’t already, create a repository for your project on GitHub.
To proceed with deployment, you will need to add two files to your repository:
netlify.toml
andpackage.json
. Download them, add them to your repo, and merge changes before proceeding.Log in to Netlify. On the “Team Overview” page, click the button that says “New Site from Git.”
Next you’ll want to “Connect to Git Provider.”
If you see “no repositories found” you will be prompted to configure Netlify on GitHub.
Once this configuration is complete, choose the repository you would like to preview.
Set the “build command” as
npm run build
and the “publish directory” assite
.Hit “Deploy Site.” Depending on the size of your project, this may take a few moments. Follow along with the build process (and check for errors) by navigating to “Publication Deploys” section and scrolling down to the “Deploy Log”.
You will be given a default URL to preview your project. You can rename this URL by navigating to “Site settings” and changing the site name. (You also have the option to buy a domain or set-up a domain you already own.)
Should you need to make any updates to your site, just merge the changes and Netlify will automatically update your preview link. You can check “Production Deploys” in the site overview section to these track changes.
- Now that you have linked Netlify to your Github account, you’ll see notifications about Netlify testing the site each time you submit a new pull request. If the checks pass, you can click the bottom-most link to launch a preview of your site. If the checks fail, there may be broken links, incorrect YAML, or other issues with your project files.
GitHub Pages
GitHub enables you to not only host your project code, but you can also use it to host a live version of your site. Learn more on the GitHub Pages website.
- If you try the Netlify option before trying GitHub Pages, remove the
site.zip
folder before making any commits. This will not break anything but it will add an unnecessary file to your project.
Preview Your Project with Github Pages
First, if you haven’t already, follow the steps to host your project’s code on GitHub in the GitHub section of our documentation to create a repository for your project.
In your text editor, open the
config/environments/github.yml
file.Update the
baseURL
to correspond to your own GitHub site. It will follow the pattern: https://YOUR-USERNAME.github.io/YOUR-PROJECT-DIRECTORY-NAME/. So, if your GitHub username is bonjovi and your project file is blaze-of-glory, yourbaseURL
would be https://bonjovi.github.io/blaze-of-glory/. (Note: your GitHub username can also be your organization name if that is how your account is set-up in GitHub.)Set the
canonifyURLs
totrue
.Next, navigate to
themes/default/webpack/webpack.config.prod.js
.So that the site fonts display properly, change line 80 to
outputPath: "YOUR-PROJECT-DIRECTORY-NAME/img/"
And change line 92 tooutputPath: "YOUR-PROJECT-DIRECTORY-NAME/fonts/"
.Commit and merge these changes to the repo.
Open Terminal, navigate to your project and enter:
bin/deploy.sh
This runs a script to deploy your site to GitHub pages. The script may ask for your GitHub username and password. (Remember that the password cursor won’t move to show that you’re typing. Just type the password and hit enter.)
If your repository is private, you will need to navigate to your repository’s settings page. Scroll down to the “Danger Zone,” click “Change project visibility” and change the visibility to public.
For “Source” switch the branch to
gh-pages
in the/(root)
folder and save.Your site should now be published at https://YOUR-USERNAME.github.io/YOUR-PROJECT-DIRECTORY-NAME.
If you make changes to your project and want to view them live, you will need to run the bin/deploy.sh
script to update your project files. Navigate to your GitHub account settings and choose “Pages” from the lefthand menu. Your refreshed link will be at the top of the page. A green box indicates the site has been published and is now live.