dannyweeks / mersey
Establish ssh connections to quickly to any registered servers.
Installs: 46
Dependents: 0
Suggesters: 0
Security: 0
Stars: 5
Watchers: 3
Forks: 0
Open Issues: 3
Type:project
Requires
- geerlingguy/ping: ^1.0
- illuminate/container: 5.2.21
- illuminate/contracts: 5.2.21
- illuminate/support: 5.2.21
- justinrainbow/json-schema: ^1.5
- symfony/console: ^2.7
- vlucas/phpdotenv: ^2.2
Requires (Dev)
- mockery/mockery: ^0.9.4
- ofbeaton/console-tester: ^1.1
- phpunit/phpunit: ^4.8
- symfony/var-dumper: ^2.7
This package is not auto-updated.
Last update: 2024-11-09 19:31:12 UTC
README
A command line (CLI) tool written in PHP to simplify establishing/interacting an SSH connection to multiple servers quickly.
Some cool things you can do:
- Connect to servers.
- Connect to a server and got to a projects directory.
- Connect to a server and run a script of your choice.
I also wrote a blog post when Mersey was first released you might find interesting.
Upgrading from Mersey v1 to v2?
Prerequisites
- OS X is the only supported operating system but Linux should be fine!.
- Composer.
Installation
If it isn't already, add composers bin directory to your PATH by adding the below to your ~/.bash_profile (or ~/.bashrc).
export PATH=~/.composer/vendor/bin:$PATH
Now, install Mersey globally so you have access to it anywhere by running
composer global require dannyweeks/mersey
Initialise Mersey. This creates a hidden directory in your home to store your servers.
~/.composer/vendor/dannyweeks/mersey/init.sh
Your servers are loaded via a json file which is located ~/.mersey/servers.json. It comes populated with some example servers to help you on your way. Read the Defining Servers section for more information.
Assumptions/Default Settings
Mersey assumes your SSH key is stored ~/.ssh/id_rsa.
Mersey uses port 22 to connect the server.
However, these can be set manually on a per server basis.
Usage
Below are the commands to interact with the mersey tool.
Defining Servers
There is a small amount of setting required to get up and running. Each server is an object in a json array. A server object needs a minimum of the following:
- name: The alias of the server which will be used on the command line.
- displayName: The name of the server.
- username: The username used to logon of which the SSH key is associated with.
- hostname: The IP address or domain name of the server.
You can get started by running mersey add which will ask a series of questions and then add the defined server to your config file.
servers.json
[
{
"name": "personal",
"displayName": "Personal Server",
"username": "danny",
"hostname": "192.168.0.1"
}
]
Additional Server Settings
There are optional setting for servers which help facilitate your needs.
- sshKey: Use this private key to connect rather than the default.
- port: Use this port to make connections instead of the default for this server.
- projects: An array of project objects. Read more in the projects section
servers.json
[
{
...
"sshKey": "/path/to/another/id_rsa",
"port": 2222,
...
}
]
Projects
Add a project to a server by creating an object in the projects array of the server.
- name: The alias of the project which will be used on the command line.
- root: Location of the project root on the server.
- scripts: An array of objects. (Optional) See Scripts
servers.json
[
{
...
"projects": [
{
"name": "project",
"root": "/var/www/project",
"scripts": []
}
],
...
}
]
Scripts
Scripts are a way of running a command on a project and then exiting the session. They can be defined in two ways; either on a per project basis or globally.
A script object contains three required properties:
- name : The alias of the script which will be used on the command line.
- description : A brief description for use in Mersey.
- command : The command to be run on the server.
Before the command you define is ran mersey connects to the server and changes directory to the project's root.
An example of a script object would be:
{
"name": "pull",
"description": "Pulls the latest changes from git.",
"command": "git fetch --all; git reset --hard origin/master"
}
Per Project
A script can be defined on a project by adding it to the project's scripts array.
servers.json
[
{
...
"projects": [
{
"name": "project",
"root": "/var/www/project",
"scripts": [
{
"name": "pull",
"description": "Pulls the latest changes from git.",
"command": "git fetch --all; git reset --hard origin/master"
}
]
}
],
...
}
]
Global Scripts
Global scripts are defined in their own file: ~/.mersey/scripts.json. Global scripts can be run on any project.
The scripts.json must be a json array containing script objects.
scripts.json
[
{
"name": "pull",
"description": "Pulls the latest changes from git.",
"command": "git fetch --all; git reset --hard origin/master"
}
]
Full Example Server Definition.
Below is a an example of a server called personal with one project called project. project has a script attached
to it called clean.
[
{
"name": "personal",
"displayName": "Personal Server",
"username": "danny",
"hostname": "192.168.0.1",
"sshKey": "/path/to/another/id_rsa",
"port": 2222,
"projects": [
{
"name": "project",
"root": "/var/www/project",
"scripts": [
{
"name": "clean",
"description": "Empty the log.",
"command": "cat /dev/null > /var/www/project/project.log"
}
]
}
]
}
]
Upgrade Guide
Upgrading To Version 2
Update Mersey via Composer.
composer global require dannyweeks/mersey:^2
Create global scripts file.
cp -i ~/.composer/vendor/dannyweeks/mersey/scripts.json.example ~/.mersey/scripts.json
Convert project scripts to objects.
The way scripts are defined has changed therefore must be updated open ~/.mersey/servers.json. See the scripts per project section for more details.
Contributing
All pull requests and bug fixes are welcomed. Please check the CONTRIBUTING file for more information.