Skip to content
This repository has been archived by the owner on Oct 5, 2020. It is now read-only.

Latest commit

 

History

History
215 lines (115 loc) · 8 KB

INSTALL.mdown

File metadata and controls

215 lines (115 loc) · 8 KB
Raw

Deploying to a server

Preparing local and remote for PM2 (one-time task)

To deploy, make sure both your local machine and your remote server/deployment target have pm2 installed with:

npm install pm2 -g

While on the server, also check if the RSA key fingerprint of your git server has been added to the known_hosts list in your own profile on the server. You can do that with:

ssh -T [email protected]` (for instance ssh -T [email protected])

If it asks to continue, answer with yes. It should print a message similar to this:

Warning: Permanently added 'github.com,192.30.253.113' (RSA) to the list of known hosts.

Optionally, ask IT to create a pm2 user. Once they have, run:

sudo pm2 startup centos -u pm2 --hp /home/pm2 --no-daemon
sudo service pm2-init.sh start

Preparing your project for PM2 (one-time task)

On your local machine, make sure you have the file ecosystem.json with any saved deployment targets inside, to create this file or add a new deployment target run:

gulp add-deploy-target

Note: This command may not work on older projects! If it's not available you will need to modify the ecosystem.json file manually.

ecosystem.json will include any config as well as any deployment config along with your credentials. If you need to put in any credentials or sensitive information that can't be in the repository then answer the final question from gulp add-deploy-target with a yes and it will put the deployment config into local.ecosystem.json.

Initial deployment of the middle-tier (one-time task)

Once you've got your TARGETNAME (answer to the first question in gulp add-deploy-target) you can initialize the target host with:

pm2 deploy TARGETNAME setup

Then deploy your latest code from your git repository and run any post-deploy commands with:

pm2 deploy TARGETNAME

Note, files deployed using pm2, will have your ownership. If someone else needs to run a pm2 deploy for the same project, you may need to go onto the server, and sudo chown user and/or group for the entire project directory.

Hint, pm2 automatically looks for ecosystem.json in your current directory, but you can use your local.ecosystem.json configuration with pm2 deploy local.ecosystem.json TARGETNAME

If you have files you haven't commited, pm2 will ask you to commit them before deploying, to ignore this use --force:

pm2 deploy TARGETNAME --force

Starting the middle-tier service on the server (one-time task)

You will now need to ssh into the server, once you've ssh'd in it's very Important that when deploying to a secure server that you do all pm2 commands as the pm2 user by using:

sudo su pm2

You can then navigate to the app's folder that you chose during gulp add-deploy-target.

Once you're in the folder you should have 3 folders: 'current', 'shared', and 'source'; go into the current folder:

cd current

You can now launch the app using pm2 with:

pm2 startOrRestart ecosystem.json

You can also launch the app using different environment configurations in ecosystem.json (env name prefixed with "env_"), for example:

pm2 startOrRestart ecosystem.json --env prod

You should then save your current pm2 deployments with:

pm2 save

Running pm2 save whenever you deploy a new app is very important as in the event of a server restart the previously saved apps will be resurrected.

Initial deployment of the back-end

If dev or prod configuration does not exist yet, run:

gulp init-dev (or gulp init-prod depending on need)

Provide settings as needed. After that you follow the same steps as for deploying to your local MarkLogic, but with a different environment parameter:

./ml dev bootstrap
./ml dev clean content
./ml dev deploy modules
./ml dev deploy content
./ml dev mlcp -options_file import-sample-data.options

(Or ./ml prod .. depending on need. Check README.mdown to see if the deployment steps have been altered for this project.)

Deploying updates

Deploying updates is a matter of repeating part of the initial deployment. For fully updating the back-end you repeat:

./ml dev bootstrap
./ml dev clean content (Be careful with cleaning content on production!)
./ml dev deploy modules
./ml dev deploy content
./ml dev mlcp -options_file import-sample-data.options

The middle-tier service is started on the server, and will not have to be stopped or restarted when deploying updates. pm2 will automatically restart the app if any of it's files are changed so all you need to do from your local machine is:

pm2 deploy TARGETNAME

And the pm2 will automatically restart the app with any changes!

Initializing httpd (one-time task)

Next to this, you likely want to enable the httpd daemon. Often only very limited ports are exposed on servers, and we usually deliberately configure the middle-tier outside that scope. Add a forwarding rule for the appropriate dns:

  • sudo chkconfig --levels 2345 httpd on

  • sudo service httpd stop

  • sudo vi /etc/httpd/conf/httpd.conf, uncomment the line with:

    NameVirtualHost *:80

  • and append:

    <VirtualHost :80> ServerName @sample-app-name.demoserver.com RewriteEngine On RewriteRule ^(.)$ http://localhost:@node-port$1 [P]

  • sudo service httpd start

Operational tasks

To view all running pm2 applications use:

pm2 list

To view any logs use:

pm2 logs

To monitor ram or cpu usage use:

pm2 monit

If you've deployed applications previously but don't see them when you run pm2 list then it might be because you're not logged in as the pm2 user or you deployed them under a different user.

If you accidently launch pm2 under your own account then you can kill the process with:

pm2 kill

And if you accidently run that command when logged in as the pm2 user then you can start pm2 and resurrect all processes from the last pm2 save with:

pm2 resurrect

For more information use the help commands or consult the documentation here:

pm2 help

pm2 deploy help

Converting an existing project

If you've previously deployed an application using linux server scripts then you will need to remove the scripts and the old deployment.

To minimize application downtime, you should configure and deploy the project using pm2 before removing the old deployment.

When converting a project to pm2 you should create an ecosystem.json file with your desired deployment config and commit it into the project, follow the above instructions and deploy it to your target server. pm2 will deploy the project to /space/projects/{appname}/source. Don't run pm2 startOrRestart ecosystem.json yet though!

Now once you've almost finished deploying with pm2 you will need to stop it with the service scripts:

sudo service stop {appname}

If you have a {appname}-watch script then stop that as well:

sudo service stop {appname}-watch

You should now be able to run pm2 startOrRestart ecosystem.json

Now that the project is deployed and assuming it's running okay you will need to clean up the old deployment.

Firstly, remove the chkconfig

sudo chkconfig --del {appname}

And also for the watch script if appropriate

sudo chkconfig --del {appname}-watch

Then delete the scripts

sudo rm /etc/init.d/{appname}

sudo rm /etc/{appname}

And for the watch script:

sudo rm /etc/init.d/{appname}-watch

sudo rm /etc/{appname}-watch

Older projects were typically deployed using a .git .live folder structure, since we no longer need these you can delete them:

rm -r /space/projects/{appname}.git

rm -r /space/projects/{appname}.live

Finally delete the git remote that pointed to the .git folder from your laptop:

cd to your project directory and run:

git remote rm {DeploymentName}

You can then finish off by deleting the old etc folder from the project folder as the scripts and documentation inside should no longer be needed:

rm -r ./etc

You should also copy THIS Install guide to your projects repository for the benefit of other users.