Setup Site for a Delivery Environment
In this section, we will be working in the delivery environment of CrafterCMS and describing how to setup your site 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, if it's not under the default path (~/.ssh/id_rsa), when authenticating 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 (default private key path with no passphrase) init-site 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 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
We recommend using Secure Shell (SSH) with your site’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 need to be generated using
RSAas the algorithm and withno passphrase.Crafter requires the key to be
RSAand does not support keys generated using an algorithm other thanRSA. The Jsch library that Jgit uses only supportsRSAand does not support other keys such as OpenSSH. Crafter also currently doesn’t support using a passphrase with SSH keys.To generate your Secure Shell (SSH) keys for authentication, run the following command
ssh-keygen -m PEM -b 4096 -t rsa. 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. . .Check that the file starts with the following header:
-----BEGIN RSA PRIVATE KEY-----to verify that the key is usingRSA.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 site’s published repo Git url when using a local repository:
/opt/crafter/authoring/data/repos/sites/mysite/published
Note
When using
ssh, you might see in the logscom.jcraft.jsch.JSchException: UnknownHostKeyerrors. 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 underSSH Unknown Hostto resolve them.Gitneeds 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 site, open a browser and type in the url of your site.
If you have multiple sites setup, to view a certain site, in your browser, enter the following:
<your url>?crafterSite=<site name>
Here we have an example of a delivery setup in another directory on disk (local), where there are two sites, myawesomesite and helloworld
To set the site to the helloworld site, in your browser, type in
http://localhost:9080?crafterSite=helloworld
To set the site to the myawesomesite, in your browser, type in
http://localhost:9080?crafterSite=myawesomesite
