{"id":30046692,"url":"https://github.com/klaus-strele/shipshape","last_synced_at":"2026-01-20T16:55:15.097Z","repository":{"id":307355169,"uuid":"1029164151","full_name":"klaus-strele/shipshape","owner":"klaus-strele","description":"shipshape is a simple command-line tool to facilitate the deployment of applications to a local server in a Windows environment.","archived":false,"fork":false,"pushed_at":"2025-07-30T21:16:24.000Z","size":11,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-30T21:49:47.692Z","etag":null,"topics":["deployment","npm-package","windows"],"latest_commit_sha":null,"homepage":"https://www.strele.com/shipshape/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/klaus-strele.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-30T16:05:30.000Z","updated_at":"2025-07-30T21:16:27.000Z","dependencies_parsed_at":"2025-07-30T21:49:50.403Z","dependency_job_id":"31ba409d-c0c6-4790-955d-e303a74348cd","html_url":"https://github.com/klaus-strele/shipshape","commit_stats":null,"previous_names":["klaus-strele/shipshape"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/klaus-strele/shipshape","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klaus-strele%2Fshipshape","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klaus-strele%2Fshipshape/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klaus-strele%2Fshipshape/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klaus-strele%2Fshipshape/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/klaus-strele","download_url":"https://codeload.github.com/klaus-strele/shipshape/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klaus-strele%2Fshipshape/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269227850,"owners_count":24381837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-07T02:00:09.698Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deployment","npm-package","windows"],"created_at":"2025-08-07T08:53:17.570Z","updated_at":"2026-01-20T16:55:15.071Z","avatar_url":"https://github.com/klaus-strele.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **shipshape - a local Windows Deployer**\n\nshipshape is a simple command-line tool to facilitate the deployment of applications to a local server in a **Windows environment**.\n\n**Note:** This tool is designed for and will only run on Microsoft Windows.\n\n## **Features**\n\n* Copies build artifacts from a source directory to a destination.  \n* Executes pre-deployment commands (e.g., running a build script).  \n* Executes post-deployment commands (e.g., restarting a server).  \n* Configuration driven by a simple `json` file.\n* Environment-specific deployments with different configurations.\n\n## **Prerequisites**\n\n* [Node.js](https://nodejs.org/) (version 20 or higher)  \n* Microsoft Windows Operating System\n\n## **Installation**\n\nInstall the package globally using npm. This will make the `shipshape` command available in your command line or PowerShell.\n\n```cmd\nnpm install -g @kstrele/shipshape\n```\nIn case you have downloaded or cloned the github repository, you can install it from within its root folder with:\n\n```cmd\nnpm install -g .\n```\n\n## **Usage**\n\n### **Basic Usage**\n\n```cmd\nshipshape [options]\n```\n\n### **Command Line Options**\n\n* `-e, --env \u003cenvironment\u003e`: Specify the target environment (e.g. DEV, UAT, PROD)\n* `-v, --version`: Show version number\n* `-h, --help`: Show help message\n\n### **Examples**\n\n```cmd\n# Deploy to default environment\nshipshape\n\n# Deploy to specific environment\nshipshape --env UAT\nshipshape -e PROD\n\n# Show help\nshipshape --help\n```\n\n### **Configuration Setup**\n\n1. **Create a Configuration File**\n    In the root directory of the project you want to deploy, create a file named `shipshape.config.json`\n\n    **Option 1: Environment-specific Configuration (Recommended)**\n    ```json\n    {\n      \"default\": {\n        \"source\": \"./dist\",\n        \"preDeploy\": [\n          \"npm install\",\n          \"npm run build\"\n        ],\n        \"postDeploy\": []\n      },\n      \"environments\": {\n        \"DEV\": {\n          \"destination\": \"C:\\\\inetpub\\\\wwwroot\\\\myapp-dev\",\n          \"postDeploy\": [\n            \"echo Deployed to DEV environment\"\n          ]\n        },\n        \"UAT\": {\n          \"destination\": \"C:\\\\inetpub\\\\wwwroot\\\\myapp-uat\",\n          \"preDeploy\": [\n            \"npm run build\",\n            \"npm run test\"\n          ],\n          \"postDeploy\": [\n            \"echo Deployed to UAT environment\",\n            \"echo Running smoke tests...\"\n          ]\n        },\n        \"PROD\": {\n          \"destination\": \"\\\\\\\\server\\\\share\\\\myapp-prod\",\n          \"preDeploy\": [\n            \"npm run build\",\n            \"npm run test\",\n            \"npm run lint\"\n          ],\n          \"postDeploy\": [\n            \"echo Deployed to PROD environment\",\n            \"echo %date% %time% \u003e\u003e deployment.log\"\n          ]\n        }\n      }\n    }\n    ```\n\n    **Option 2: Simple Default Configuration**\n    \n    ```json\n    {\n      \"default\": {\n        \"source\": \"./dist\",\n      \t\"destination\": \"C:\\\\path\\\\to\\\\your\\\\application\\\\root\",  \n        \"preDeploy\": [\n          \"npm install\",\n          \"npm run build\"\n        ],\n        \"postDeploy\": [  \n          \"iisreset /stop\",  \n          \"iisreset /start\"  \n        ]  \n      }\n    }\n    ```\n    \n2. **Configure package.json**  \n    In your project's `package.json`, add deployment scripts:\n\n    ```json\n    \"scripts\": {  \n      \"deploy\": \"shipshape\",\n      \"deploy:dev\": \"shipshape --env DEV\",\n      \"deploy:uat\": \"shipshape --env UAT\",\n      \"deploy:prod\": \"shipshape --env PROD\"\n    }     \n    ```\n\n3. **Run the Deployment**  \n   Execute the script from your project's root directory:\n\n   ```cmd \n   # Deploy to default environment (DEV)\n   npm run deploy\n   \n   # Deploy to specific environments\n   npm run deploy:dev\n   npm run deploy:uat\n   npm run deploy:prod\n   \n   # Or use shipshape directly\n   shipshape --env PROD\n   ```\n\n   The tool will then:  \n   1. Run the commands listed in `preDeploy`.\n   2. Create the `destination` directory if it does not exist or empty an existing directory while keeping those files and subfolders in `keepList`.\n   3. Copy the contents of the `source` directory to the `destination`.  \n   4. Run the commands listed in `postDeploy`.\n\n## **Configuration Options**\n\n### **Environment-specific Configuration**\n\nWhen using environment-specific configuration, the structure is:\n\n* `default` Base configuration that applies to all environments\n* `environments` Environment-specific overrides\n\nEach environment configuration can override any property from the default configuration.\n\n### **Configuration Properties**\n\n* `source` (string, **required**): The path to the directory containing the files to be deployed (e.g., dist, build). This is relative to the project root.  \n* `destination` (string, **required**): The absolute path to the target deployment directory on your local server.  \n* `preDeploy` (array of strings, optional): A list of commands to execute before the files are copied. These are run in the *project's root directory*.  \n* `postDeploy` (array of strings, optional): A list of commands to execute after the files have been copied. These are run in the *destination* directory unless it is a **UNC path**. In this case it falls back to the *project's root directory*.\n* `keepList` (array of strings, optional): A list of files or directories in the destination that should be preserved during deployment. These will not be deleted when the destination is emptied.\n\n### **Keep List Feature**\n\nThe `keepList` allows you to preserve important files and directories in the destination during deployment:\n\n```json\n{\n  \"default\": {\n    \"source\": \"./dist\",\n    \"keepList\": [\n      \"web.config\",\n      \"logs\",\n      \".env\",\n      \"uploads\"\n    ]\n  },\n  \"environments\": {\n    \"PROD\": {\n      \"destination\": \"C:\\\\inetpub\\\\wwwroot\\\\myapp-prod\",\n      \"keepList\": [\n        \"web.config\",\n        \"logs\",\n        \"uploads\",\n        \"user-data\",\n        \"certificates\",\n        \"deployment.log\"\n      ]\n    }\n  }\n}\n```\n\n**Note:** entries in the `keepList` are case-insensitive but will be converted to uppercase internally\n\n**Common files to preserve:**\n\n- `web.config` - IIS configuration files\n- `logs` - Application log directories\n- `.env` - Environment configuration files\n- `uploads` - User-uploaded content\n- `certificates` - SSL certificates\n- `user-data` - Persistent user data\n- Configuration files specific to the deployment environment\n\n### **Environment Selection**\n\n* For environment-specific configurations: Valid environments are dynamically read from the `environments` section\n* Environment names are case-insensitive but will be converted to uppercase internally\n* You can define custom environments like `LOCAL`, `DEVELOPMENT`, `STAGING`, `INTEGRATION`, `PRODUCTION`, etc.\n\n### **Custom Environments Example**\n\nYou can define any environments you need:\n\n```json\n{\n  \"default\": {\n    \"source\": \"./dist\",\n    \"preDeploy\": [\"npm run build\"]\n  },\n  \"environments\": {\n    \"LOCAL\": {\n      \"destination\": \"C:\\\\temp\\\\myapp-local\"\n    },\n    \"DEVELOPMENT\": {\n      \"destination\": \"C:\\\\inetpub\\\\wwwroot\\\\myapp-dev\"\n    },\n    \"STAGING\": {\n      \"destination\": \"C:\\\\inetpub\\\\wwwroot\\\\myapp-staging\",\n      \"preDeploy\": [\"npm run build\", \"npm run test\"]\n    },\n    \"PRODUCTION\": {\n      \"destination\": \"C:\\\\inetpub\\\\wwwroot\\\\myapp-prod\",\n      \"preDeploy\": [\"npm run build\", \"npm run test\", \"npm run lint\"]\n    }\n  }\n}\n```\n\nThen deploy with: `shipshape --env STAGING` or `shipshape --env LOCAL`\n\nThis setup provides a straightforward way to automate your local deployment process on Windows with support for multiple environments.\n\nLicense\n-------\n\nLicensed under MIT\n\nCopyright (c) 2025 [Klaus Strele](https://github.com/klaus-strele)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklaus-strele%2Fshipshape","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fklaus-strele%2Fshipshape","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklaus-strele%2Fshipshape/lists"}