{"id":15877537,"url":"https://github.com/zimbatm/apiece","last_synced_at":"2025-04-01T23:23:42.536Z","repository":{"id":66382093,"uuid":"60277724","full_name":"zimbatm/apiece","owner":"zimbatm","description":"Bootstrap, develop, build and run applications in Docker or locally","archived":false,"fork":false,"pushed_at":"2023-12-15T14:36:59.000Z","size":33,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-07T15:15:50.371Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zimbatm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2016-06-02T15:58:49.000Z","updated_at":"2020-07-21T16:35:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"cb4db78c-7462-47e9-9419-9ea6b6195a93","html_url":"https://github.com/zimbatm/apiece","commit_stats":{"total_commits":39,"total_committers":1,"mean_commits":39.0,"dds":0.0,"last_synced_commit":"e4f2b7d5372b025c7ef1cad864b08233918dc4ab"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zimbatm%2Fapiece","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zimbatm%2Fapiece/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zimbatm%2Fapiece/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zimbatm%2Fapiece/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zimbatm","download_url":"https://codeload.github.com/zimbatm/apiece/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246725967,"owners_count":20823702,"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":[],"created_at":"2024-10-06T02:01:47.229Z","updated_at":"2025-04-01T23:23:42.515Z","avatar_url":"https://github.com/zimbatm.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# apiece\n\nBootstrap, develop, build and run applications in Docker or locally.\n\nUses base images for bootstrapping applications, which include scripts for\nbuilding and running the created application in consistent, isolated\n[environments](#environments).\n\nDisclaimer: it's still a beta-quality software, there are some rough edges, such\nas error handling and logging.\n\n## Requirements\n\n* Docker 1.6.0+\n* Git\n\n## Installation\n\nTODO: There are binaries in GitHub releases, but they are not built\nautomatically and are only provided for Linux.\n\n## Basic usage\n\nStart by creating an application using `apiece new` specifying the base image\nand the name of your app.\n\n```bash\napiece new https://github.com/pl/apiece-base-express-4 apiece-hello-world\ncd apiece-hello-world\n```\n\nBuild the application using Docker:\n\n```bash\napiece build\n```\n\nStart the server and expose the application port:\n```bash\napiece run -p 1234\n```\n\nCheck that the application is running:\n```bash\ncurl http://localhost:1234\n```\n\n## Environments\n\nThere are 3 environments supported by apiece: `production` (default),\n`development` and `local`. Each of the environments supports separate\n`build`/`run`/`exec`/`clean` scripts and mounted data directories.\n\nFollowing table illustrates the differences between the environments:\n\n                                   | production | development | local\n-----------------------------------|------------|-------------|------\nruns in Docker                     | Y          | Y           |\nrequires local application runtime |            |             | Y\nsupports persistent data           | Y          | Y           | Y\nsupports live application updates  |            | Y           | Y\nalways starts in clean environment | Y          |             |\n\n### Docker\n\nContainerized environments run applications in Docker containers, which provide\nisolation between the host system (e.g. server or development machine).\n\n### Local Application Runtime\n\nWhen using Docker, the host system does not need to provide application runtime\n(e.g. Ruby for Rails applications) - everything is included in the Docker image.\n\n### Persistent Data\n\nEach environment exposes a dedicated data folder, which is persisted between\napplication restarts on given host.\n\n### Live Application Updates\n\nSome base images support live application updates. For example, Rails can\nrefresh the code after modifications without restarting the application itself.\nSuch updates are supported by `development` and `local` environments to make\nprogrammer's life easier.\n\n### Clean Environment\n\nProduction applications and tests should be run in a clean environment to make\nexecution repeatable. Although using clean environments is advised, it is not\npossible to support it along live updates.\n\n## Application Layout\n\nWhen bootstrapping an application, apiece creates an `apiece.io` directory\nin the root of the project. This folder contains:\n\n* build hooks (production, development, local)\n* exec hooks (production, development, local)\n* run hooks (production, development, local)\n* clean hooks (development, local)\n* Docker files (production, development)\n* data directories (production, development, local)\n* app-name file containing the application name\n\nCommand hooks and Docker files can be modified whenever needed, just make sure\nthey respect semantics of their environments.\n\n## Commands\n\nAll commands and available options can be found by running `apiece -h`.\n\n### new\n\n```\nnew \u003cbase\u003e \u003cname\u003e\n```\n\nBootstraps a new application from given base image in a new directory.\n\nApplication name format may differ between base images. More information can be\nfound in the specific base image repository README file.\n\n### build\n\n```\nbuild local [-d DIR]\nbuild [dev] [-d DIR --forward-ssh-agent]\n```\n\nBuilds the application in given environment.\n\n### run\n\n```\nrun local [-d DIR -b \u003cbind\u003e -p \u003cport\u003e] [--] \u003cargs\u003e...\nrun [dev] [-d DIR -b \u003cbind\u003e -p \u003cport\u003e --forward-ssh-agent --net=NETWORK --dockeropt=OPT...] [--] \u003cargs\u003e...\n```\n\nRuns the application in given environment using the last build. Supports\nexposing the application port and SSH agent sock forwarding for containerized\nenvironments.\n\nBy default, Docker networking runs in the bridge mode. It is possible to switch\nto the host mode by passing `--net=host` and the port number.\n\nBind address can be specified using `-b` or `--bind`. By default applications\nare bound to `127.0.0.1`.\n\n### exec\n\n```\nexec local [-d DIR] [--] \u003ccommand\u003e...\nexec [dev] [-d DIR --forward-ssh-agent --dockeropt=OPT...] [--] \u003ccommand\u003e...\n```\n\nExecutes am arbitrary command in the environment context.\n\n### clean\n\n```\nclean local [-d DIR]\nclean dev [-d DIR --dockeropt=OPT...]\n```\n\nRemoves artifacts created by the application inside the working directory.\nUseful for cleaning up logs and temporary files that can't be places outside the\nworking directory and need to be removed before switching between `local` and\n`development` environments.\n\nFor example, Rails creates a local `tmp` directory with compiled assets, which\nwhen created in the `dev` will be owned by the user running the docker daemon\n(usually root).\n\n### info name\n\nReturns the name of the application.\n\n## Base Images\n\nBase images are implemented as git repositories. Currently there is no registry,\nso when creating a new application the base needs to be specified as a git URL.\n\n### Existing Bases\n\nPlease send a pull request to include your base on this list.\n\n* https://github.com/pl/apiece-base-express-4\n* https://github.com/pl/apiece-base-go-http\n* https://github.com/pl/apiece-base-rails-4\n\n## Build Instructions\n\nIn order to build apiece, Rust 1.1.0+ and Cargo must be installed. Running\n\n```\ncargo build --release\n```\n\nwill build the binary and place it in `target/release/apiece`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzimbatm%2Fapiece","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzimbatm%2Fapiece","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzimbatm%2Fapiece/lists"}