Ensure your project's package.json
file contains the following:
package.json"engines" : {"node": "6","npm": "3"},"dependencies": {"docpad": "6","docpad-plugin-blah": "2"},"main": "node_modules/.bin/docpad-server","scripts": {"start": "docpad-server","test": "docpad generate --debug --silent --env static","info": "docpad info --silent"}
Correct dependencies with what you are actually using.
Perform a generation for a static production environment using docpad generate --env static
Upload the generated directory to your server's public_html
or htdocs
directory
If you use rsync, checkout our DocPad rsync deploy script​
Install the GitHub Pages Plugin​
docpad install ghpages
Deploy to GitHub Pages using the plugin
docpad deploy-ghpages --env static
If you'd like deployment automatically to GitHub Pages every time your repo updates, check out the Continuous Deployment Guide​
Create a Procfile
file inside your project that contains:
Procfileweb: npm start
Set your heroku instance to run in production mode
heroku config:add NODE_ENV=production
If you're also wanting to use custom domains for your website, follow the Heroku Guide here, or alternatively here is a generic guide:
Login to your domain's DNS manager
Create an CNAME Record for your domain pointing to your app url (e.g., balupton.herokuapp.com
)
Create your OpenShift account and install their client tools​
Create a new OpenShift application for your project:
rhc app create PROJECTNAME https://raw.githubusercontent.com/kyrylkov/openshift-iojs/master/metadata/manifest.yml
Set environment variables using:
rhc set-env -a PROJECTNAME NODE_ENV='production'
If you'd like a custom domain, run:
rhc alias-add PROJECTWEBSITE.COM -a PROJECTNAME
Then create CNAME record with your DNS host pointing PROJECTWEBSITE.COM
to PROJECTNAME-YOUR_OPENSHIFT_NAMESPACE.rhcloud.com
If you don't know what your OpenShift namespace is, run:
rhc app show -a PROJECTNAME
And it will be listed within the SSH URL.
Deploy your project's code to openshift:
rhc app deploy "https://github.com/USER/REPO.git#master" -a PROJECTNAME
You should be all good now! Check the logs of your app with:
rhc tail -a PROJECTNAME
Create a deployment script that triggers the static content generation. To create the script run the following command using the Windows Azure Cross-Platform Command-Line Interface:
azure site deploymentscript --basic -t bash
Modify the deploy.sh
file by changing the # Deployment
section to the following lines. You can see a complete example of the deploy.sh file here.
deploy.shecho Handling deployment.​# 1. Install npm packagesif [ -e "$DEPLOYMENT_SOURCE/package.json" ]; thencd "$DEPLOYMENT_SOURCE"npm install --production --silentexitWithMessageOnError "npm failed"cd - > /dev/nullfi​# 2. Build DocPad Siteecho Building the DocPad sitecd "$DEPLOYMENT_SOURCE"npm testexitWithMessageOnError "DocPad generation failed"​# 3. KuduSyncecho Kudu Sync from "$DEPLOYMENT_SOURCE/out" to "$DEPLOYMENT_TARGET"$KUDU_SYNC_COMMAND -q -f "$DEPLOYMENT_SOURCE/out" -t "$DEPLOYMENT_TARGET" -n "$NEXT_MANIFEST_PATH" -p "$PREVIOUS_MANIFEST_PATH" -i ".git;.deployment;deploy.sh" 2> /dev/nullexitWithMessageOnError "Kudu Sync failed"
Last, create a web.config
file in the static
directory of your site with the URL rewrite rules shown below. These rules remove the HTML extensions from your URLs. You can see the main portions of this web.config
file below. You can download the complete file here.
web.config<rule name="RemoveHTMLExtensions" stopProcessing="true"><match url="^(.*)\.html$" /><action type="Redirect" url="{R:1}" appendQueryString="true" /></rule><rule name="RewriteHTMLExtensions" stopProcessing="true"><match url="(.*)" /><conditions><add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true"/><add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true"/></conditions><action type="Rewrite" url="{R:1}.html" /></rule>
Inside your project directory, do the following:
Add the GitHub Pages Plugin as a Development Dependency
npm install --save-dev docpad-plugin-ghpages
Add a deploy script to your package.json
"scripts"
section:
package.json{"scripts": {"deploy": "docpad deploy-ghpages --silent --env static"}}
Remove the regenerateEvery
property from your DocPad Configuration File if you have set it, as it will no longer be needed.
Using Travis CI
Inside your GitHub account, do the following:
​Create a Personal Access Token called Travis CI Deployer
that has repo
and public_repo
checked (uncheck everything else), make note of the token we'll use it later (this same token can be used for all the repos you have access to).
Enable Travis CI for the repository, then inside the repository directory, do the following:
Add this .travis.yml
file to your project (make any necessary changes to the Custom Configuration section).
Run the following commands (with the appropriate substitutions):
travis encrypt "DEPLOY_USER=$YOUR_GITHUB_USERNAME" --add env.globaltravis encrypt "DEPLOY_TOKEN=$THE_PERSONAL_ACCESS_TOKEN" --add env.global
Commit and push the changes.
If you want to regenerate your website when an external GitHub Repository changes (for instance updating the DocPad Website when the DocPad Documentation repository changes), you will need to Enable Travis CI for that repository, then inside that repository directory, do the following:
Add this .travis.yml
file to your project (make any necessary changes to the Custom Configuration section).
Run the following commands (with the appropriate substitutions):
travis encrypt "GITHUB_TRAVIS_TOKEN=$THE_PERSONAL_ACCESS_TOKEN" --add env.global
Commit and push the changes.
All done, your next push to master will be automatically deployed.
Using Circle CI
Inside your project directory, do the following:
Add this circle.yml
file to your project (make any necessary changes to the Custom Configuration section).
Commit and push the changes.
Create a SSH Key that will be used by Circle CI to deploy to GitHub Pages, do this by:
Create the SSH Key, make note of where it goes, don't bother with a password, use the email that was inside your circle.yml
file:
ssh-keygen -t rsa -b 4096 -C "[email protected]"
Make note of it's location. Two files will be generated. One with .pub
at the end, which is the public key, and one without .pub
which is the private key.
Inside your Circle CI account, do the following:
Add any environment variables you may need via Project Settings -> Tweaks -> Environment Variables
Add the private key to CircleCI via Project Settings -> Permissions -> SSH Permissions
. Set the hostname to github.com
. Use the contents of the private key file for the private key text area.
Inside your GitHub Project Settings, do the following:
Add the public key to your GitHub Project by going to Settings -> Deploy Keys -> Add deploy key
. Specify the title as CircleCI Deployment
or whatever you like and set the key text area to the contents of the public key. Allow write access.
If you want to regenerate your website when an external GitHub Repository changes (for instance updating the DocPad Website when the DocPad Documentation repository changes), you will need to:
Create yourself a Circle CI token via the Circle CI Account API Page​
Go to the settings of the GitHub Repository that should cause the regeneration, and access Webhooks & Services -> Add webhook
Specify the Payload URL
to be:
https://circleci.com/api/v1/project/YOUR_GITHUB_ORG/YOUR_GITHUB_REPO/tree/master?circle-token=THE_CIRCLECI_TOKEN
Specify Content type
to be application/json
, select Just the push event
, and check Active
You can hit that Payload URL whenever you want to retest and rebuild your project.
All done, your next push to master will be automatically deployed.
You can now delete the local SSH key files that were made, as they serve no further purpose.
Project repository must be at GitLab. If it is already somewhere else, GitLab allows to setup automatic mirroring.
Just add single file .gitlab-ci.yml
to project root:
.gitlab-ci.ymlimage: node​cache:paths:- node_modules/​pages:before_script:- npm install --productionscript:- npm test- mv out publicartifacts:paths:- publiconly:- master