• Document Up to Date
  • Updated On 4.0.2

Setup Project for a Delivery Environment

In this section, we will be working in the delivery environment of CrafterCMS and describing how to setup your project for a delivery environment.

Setup Crafter Deployer Target

CrafterCMS out of the box has a script to help you create your deployer target for the delivery environment.

In the bin folder in your CrafterCMS delivery environment, we will use the script init-site.sh to help us create the deployer target.

From your command line, navigate to your {Crafter-CMS-delivery-environment-directory}/bin/ , and execute the init-site script. The following output of init-site.sh -h explains how to use the script:

usage: init-site [options] [site] [repo-path]
 -a,--notification-addresses <addresses>   A comma-separated list of email
                                           addresses that should receive
                                           deployment notifications
 -b,--branch <branch>                      The name of the branch to clone
                                           (live by default)
 -f,--passphrase <passphrase>              The passphrase of the private
                                           key (when the key is passphrase
                                           protected)
 -h,--help                                 Show usage information
 -k,--private-key <path>                   The path to the private key, when
                                           using private-key authentication
                                           through SSH to the remote Git repo
 -p,--password <password>                  The password for the remote Git
                                           repo, when using basic
                                           authentication
 -s,--crafter-search                       Use Crafter Search instead of
                                           Elasticsearch
 -u,--username <username>                  The username for the remote Git
                                           repo, when using basic
                                           authentication

EXAMPLES:
 Init a site from the default repo path (../../crafter-authoring/data/repos/sites/{sitename}/published)
     init-site mysite
 Init a site from a specific local repo path
     init-site mysite /opt/crafter/authoring/data/repos/sites/mysite/published
 Init a site from a specific local repo path, cloning a specific branch of the repo
     init-site -b master mysite /opt/crafter/authoring/data/repos/sites/mysite/published
 Init a site that is in a remote HTTPS repo with username/password authentication
     init-site -u jdoe -p jdoe1234 mysite https://github.com/jdoe/mysite.git
 Init a site that is in a remote SSH repo with public/private key authentication (specific private key path
 with no passphrase)
     init-site -k ~/.ssh/jdoe_key mysite ssh://myserver/opt/crater/sites/mysite
 Init a site that is in a remote SSH repo with public/private key authentication (specific private key path
 with passphrase)
     init-site -k ~/.ssh/jdoe_key -f jdoe123 mysite ssh://myserver/opt/crater/sites/mysite

Note

Remember that when using private key SSH authentication, the private key path must be set explicitly using the -k option. Here’s an example:

init-site -k ~/.ssh/jdoe_key myeditorial ssh://myserver/opt/crater/sites/myeditorial

We recommend using Secure Shell (SSH) with your project’s published repo Git url and for authentication, to use either username/password authentication or public/private key authentication.

The SSH Git URL format is: ssh://[user@]host.xz[:port]/path/to/repo/ where sections between [] are optional.

Example #1: ssh://server1.example.com/path/to/repo

Example #2: ssh://jdoe@server2.example.com:63022/path/to/repo

Note

When using ssh keys for authentication, the keys can be generated using one of the following: RSA, ECDSA, ED25519 or DSA as the algorithm and with no passphrase (Crafter currently doesn’t support using a passphrase with SSH keys.)

To generate your Secure Shell (SSH) keys for authentication, run the following command:

Generate an RSA SSH keypair with a 4096 bit private key

ssh-keygen -t rsa -b 4096

Generate an DSA SSH keypair with a 2048 bit private key

ssh-keygen -t dsa -b 1024

Generate an ECDSA SSH keypair with a 521 bit private key

ssh-keygen -t ecdsa -b 521

Generate an ed25519 SSH keypair- this is a new algorithm added in OpenSSH.

ssh-keygen -t ed25519

Your output should look something like this:

✗ ssh-keygen -m PEM -b 4096 -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/Users/myuser/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/myuser/.ssh/id_rsa.
Your public key has been saved in /Users/myuser/.ssh/id_rsa.pub.
.
.

After generating your private and public keys, you will need to add your new public key to where your remote git repository is located. If you are using GitHub, you will need to add your public key (e.g., id_rsa.pub) into your GitHub account. If your remote Git repository is hosted on a server, you will need to copy your public key (e.g., id_rsa.pub) to the host server.

If you are just working on another directory on disk for your delivery, you can just use the filesystem. When your repository is local, make sure to use the absolute path. Here is an example project’s published repo Git url when using a local repository:

/opt/crafter/authoring/data/repos/sites/my-project/published

Note

  • When using ssh, you might see in the logs com.jcraft.jsch.JSchException: UnknownHostKey errors. These errors are common in Ubuntu, and are caused by known host keys being stored in non-RSA format. Please follow the instructions in Debugging Deployer Issues under SSH Unknown Host to resolve them.

  • Git needs to be installed in authoring when using SSH to connect the delivery to the authoring.

    If you see the following error in the delivery Deployer: Caused by: java.io.IOException: bash: git-upload-pack: command not found you’ll need to add the location of git (usually /usr/bin) to your non-login shell startup file (e.g. ~/.bashrc).

    To get the location of Git, run the following command: which git-upload-pack

Viewing your Site for Testing

To test viewing your project, open a browser and type in the url of your project.

If you have multiple projects setup, to view a certain project, in your browser, enter the following:

<your url>?crafterSite=<project id>

Here we have an example of a delivery setup in another directory on disk (local), where there are two projects, my-awesome-editorial and hello-world

Setup Project for Delivery - Project List

To set crafterSite to the hello-world project, in your browser, type in

http://localhost:9080?crafterSite=helloworld
Setup Project for Delivery - Hello World Project

To set the site to the myawesomesite, in your browser, type in

http://localhost:9080?crafterSite=myawesomesite
Setup Site for Delivery - My Awesome Site