{"id":23543772,"url":"https://github.com/jimdelois/marina","last_synced_at":"2026-05-11T07:47:08.744Z","repository":{"id":147131958,"uuid":"169460766","full_name":"jimdelois/marina","owner":"jimdelois","description":"A Tool to Manage Stacks of Multiple Dockerized Applications","archived":false,"fork":false,"pushed_at":"2019-03-29T22:00:13.000Z","size":37716,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-17T09:45:10.295Z","etag":null,"topics":["development","docker","docker-compose","local-development"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jimdelois.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2019-02-06T19:07:45.000Z","updated_at":"2019-05-02T21:15:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"944f1eb4-3140-4986-964f-8d8a2f5a5532","html_url":"https://github.com/jimdelois/marina","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimdelois%2Fmarina","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimdelois%2Fmarina/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimdelois%2Fmarina/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimdelois%2Fmarina/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jimdelois","download_url":"https://codeload.github.com/jimdelois/marina/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254301618,"owners_count":22047907,"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","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":["development","docker","docker-compose","local-development"],"created_at":"2024-12-26T07:11:36.820Z","updated_at":"2026-05-11T07:47:03.719Z","avatar_url":"https://github.com/jimdelois.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Marina\n\nA tool chain to organize multiple `docker-compose`-ified applications into logical groupings known as \"Stacks,\" with a specific focus on easing the process of local development.\n\n***Marina is currently under active PoC/Development. Like, literally everything is subject to change with or without notice (but definitely without).***\n\n## Overview\n\n### Problem Space\n\nDocker-Compose improves the usability of Docker, itself, by providing configuration-driven, versionable descriptors and a DSL for `docker run` commands, backed by an intuitive CLI.  A single service within an application may require several environment variables, networking configurations, startup commands, etc, with values differing for each deployment environment.  This addition to the Docker landscape has greatly eased the management of single- and multi-service applications for all tiers of deployment, including local development.\n\nIn today's micro-service world, local development of a single application may sometimes require the coincident development of other, related applications.  Further, each application (possibly with multiple services therein) may exist in distinctly different VCS repositories and, as such, have no single, centralized `docker-compose` file to manage these cross-repo application dependencies.\n\nAn example may be a suite of applications that, together, comprise a partial E-Commerce system in the enterprise.  This subsystem may rely on multiple applications such an SPA web UX, a User Auth API, Search API, Transaction-API, etc.  On the local, it may be preferable to add a reverse proxy such as NGinx Proxy for logical and standardized request routing.  Each of these applications are developed with their own repositories and independent release cycles, etc.  Harmonizing them for local development, or even declaring them as interdependent, is well-beyond the scope of Docker Compose et al.\n\n### Proposal\nWhile tools like Swarm (etc) exist for managing Docker clusters and multiple services, and CloudFormation (etc) for invoking declarative and atomic operations of entire infrastructures (including Service deployments)...\n \n***Marina** specifically sets out to ease coincident or controlled local development of multiple Dockerized applications.*\n\nMarina does this by providing a configuration DSL to specify:\n- **Applications:** Individual VCS applications with a local `docker-compose.yml` file that specifies its all its services for the local.\n- **Stacks:** Groups of Applications, with directional dependencies as needed.\n- (There will be additional configuration categories in the future)\n\n*Note:* By separating Applications from Stacks, some Applications may be shared across entire Stacks (such as a fronting proxy, etc).\n\n## Current Usage\n\nThe CLI is the only module currently being developed.\n\n### Installation of Marina CLI\n\nDue to a complicated set of intricacies surrounding local file mounts of source directories, local storage of the `marina.json` Config file, and some chicken/egg problems, the simplest installation of the `marina` CLI tool is directly onto the Host machine (as opposed to shipping Marina as an already-Dockerized tool, itself).\n\n#### Homebrew (Recommended)\nHomebrew is by far the simplest method of installation, and allows for easily keeping the tool up-to-date.\n\n```\nbrew install jimdelois/macosx/marina\n```\n\nFor more information, visit [https://github.com/jimdelois/homebrew-macosx](https://github.com/jimdelois/homebrew-macosx)\n \n#### Manual Installation\n\n##### System Dependencies \u0026#10013;\n- Docker\n- `rm` (for the `clean` target)\n\nThe following commands will install the Marina CLI tool to `/usr/local/bin/marina`.\n\n```\n$\u003e git clone git@github.com:jimdelois/marina.git\n$\u003e cd marina\n$\u003e make \u0026\u0026 make install\n```\n\nTo remove build artifacts:\n\n```\n$\u003e make clean\n```\n\n##### Notes\n- The target install location shall be configurable in the future\n- \u0026#10013; Currently, only Mac OS is supported. It should be a trivial matter to enable the other architectures supported by `pkg`. \n\n#### Marina Development\n\nIf the Host machine has a Node 10 runtime, etc, this CLI script may simply be linked on it.  Updates to the source files will immediately be reflected in the system-linked script.\n\n```\n$\u003e git clone git@github.com:jimdelois/marina.git\n$\u003e cd marina\n$\u003e npm install\n$\u003e npm link\n```\n\nTo remove:\n\n```\n$\u003e npm rm --global marina \n```\n\n### Quick Start\n\n#### The Marina Config File\n\nMarina persists all data on the file system in a Configuration file.  You can see an example of the syntax by issuing `marina config example`.  By default, Marina will store this in `~/.marina/marina.json`.  However, this value can be overridden with the `-f` option or by supplying an environment variable of the form `MARINA_CONFIG=/path/to/marina.json`.  By placing the latter in your `~/.bash_profile` (or similar), you can effectively store the file anywhere and Marina will use it automatically.\n\nTo get started, generate a new Configuration (using the default, or any options cited above) with:\n\n```\n$\u003e marina init\n\nWrote new Config file at /Users/jimdelois/.marina/marina.json.\n```\n\n#### Defining Applications in a Stack\n\nSupposing there is a Docker-Composed **Application** rooted in the current directory, the following command will register it into Marina:\n\n```\n$\u003e marina applications add \\\n    --name \"Acme API\" \\\n    --type \"LOCAL\" \\\n    --docker-compose-filename \"docker-compose.override.yml\" \\\n    --path $(pwd)\n\nApplication \"Acme API\" added.\n```\n\n**NOTE:** Any options omitted will be requested via an interactive prompt. Relatedly, the file `docker-compose.yml` will be used if not specified.  At this time, only the `LOCAL` Application \"type\" is supported, implying a locally-defined Docker Compose -ready application.\n\nAdd another:\n\n```\n$\u003e marina applications add \\\n    --name \"Acme Website\" \\\n    --type \"LOCAL\" \\\n    --path \"/development/projects/acme/website\"\n\nApplication \"Acme Website\" added.\n```\n\nMarina **Stacks** are logical groupings of separate Applications to be interacted with collectively.  Once a Stack exists, any Applications regsitered into Marina can be added into the grouping, or removed, etc.\n\nCreate a Stack:\n\n```\n$\u003e marina stacks add --name \"The Acme Stack\"\n\nStack \"The Acme Stack\" added.\n```\n\nNow bind the two previously-created Applications to it:\n\n```\n$\u003e marina applications link \"Acme API\" \"The Acme Stack\" \u0026\u0026 \\\n   marina applications link \"Acme Website\" \"The Acme Stack\"\n\nApplication \"Acme API\" added to Stack \"The Acme Stack\".\nApplication \"Acme Website\" added to Stack \"The Acme Stack\".\n```\n\n#### Reviewing Current Configurations\n\nThere are various ways to view the current Configuration, at different levels:\n\n```\n$\u003e marina stack ls \"The Acme Stack\"\n\nSTACK NAME           ID                                   APPS\nThe Acme Stack       6f294762-b1ff-4a93-b7cb-1c160ff03404    2\n\nAPP NAME             ID                                   TYPE\nAcme API             da278a79-1bc7-470d-bc3b-9f06bdc0263e Local\nAcme Website         1f8d737c-f81d-42cf-b47f-6c01ac21622e Local\n```\n\nOr (among others - view the Help for other informative outputs), e.g.:\n\n```\n$\u003e marina config dump\n\n\u003c\u003c contents omitted \u003e\u003e\n```\n\n#### Working with Stacks\n\nThe point of Marina is to operate on Stacks (groups of Applications) as a whole.  With the definitions and associations in place, we can build all of the Applications at once and bring all services for all Applications up with commands such as the following:\n\n```\n$\u003e marina stack build \"The Acme Stack\" \u0026\u0026 \\\n   marina stack up \"The Acme Stack\"\n```\n\nAll Applications should be built and started in tandem.  Stop the containers (noting that for all \"name\" inputs, you can always specify the resource's UUID):\n\n```\n$\u003e marina stack down 6f294762-b1ff-4a93-b7cb-1c160ff03404\n```\n\n### More Usage\n\nUntil full documentation is available, use the basic `marina` command for the default Help menu:.\n\n```\n$\u003e marina\nMarina is a toolset for managing multiple Dockerized application stacks.\n\nGeneral Usage:\n marina [general options] \u003ccommand\u003e [command-specific options] [\u003c..etc\u003e]\n\nExamples:\n marina config test\n marina -f /path/to/marina.json stacks ls\n marina stack up StackName\n\nCommands:\n marina generate-completion  Generate a bash completion script\n marina applications         Interact with the collection of Applications                   [aliases: as]\n marina config               Operate with/on a given Configuration file                      [aliases: c]\n marina initialize           Creates a new Marina config file from scratch and initializes for use\n                                                                                       [aliases: init, i]\n marina stack                Interact with an individual Stack                               [aliases: s]\n marina stacks               Interact with the collection of Stacks                         [aliases: ss]\n\nOptions:\n -h, --help     Show help                                                                       [boolean]\n -f, --file     Configuration file    [string] [required] [default: \"/Users/jdelois/.marina/marina.json\"]\n --verbose      Verbose Output                                                                  [boolean]\n --debug        Debug Output                                                                    [boolean]\n -v, --version  Show version number                                                             [boolean]\n\nCopyright 2019 - Jim DeLois - https://github.com/jimdelois/marina\n```\n\n\n## General Roadmap\n- [x] Round out basic functionality\n  - [x] Basic Commands: Up/Down/Clean\n  - [x] Config\n    - [x] Stack Addition and Removal\n    - [x] Application Addition and Removal\n    - [x] Application linking/unlinking to/from Stacks\n    - [x] Export\n  - [x] Tool Initialization\n- [ ] Status Commands\n- [ ] SCM / Version Control Integration\n- [ ] Guide / Walkthrough - GitHub Pages?\n- [x] Compilation to distributable binary\n- [x] Make available in Homebrew\n- [ ] hapi.js HTTP API\n- [ ] Fronting UX App\n- [ ] Electron version of Fronting App?\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimdelois%2Fmarina","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjimdelois%2Fmarina","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimdelois%2Fmarina/lists"}