{"id":13416553,"url":"https://github.com/Stratoscale/skipper","last_synced_at":"2025-03-15T00:31:07.859Z","repository":{"id":39618536,"uuid":"65899338","full_name":"Stratoscale/skipper","owner":"Stratoscale","description":"Easily dockerize your Git repository","archived":false,"fork":false,"pushed_at":"2024-03-31T10:50:06.000Z","size":257,"stargazers_count":45,"open_issues_count":5,"forks_count":21,"subscribers_count":45,"default_branch":"upstream","last_synced_at":"2024-04-27T02:02:29.179Z","etag":null,"topics":["docker","git"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Stratoscale.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}},"created_at":"2016-08-17T10:37:53.000Z","updated_at":"2024-03-30T09:00:25.000Z","dependencies_parsed_at":"2022-07-13T09:10:32.089Z","dependency_job_id":"5da4fa28-60bc-46e8-ac79-1992fd9c9277","html_url":"https://github.com/Stratoscale/skipper","commit_stats":{"total_commits":213,"total_committers":25,"mean_commits":8.52,"dds":0.5586854460093897,"last_synced_commit":"d87841451d276e90a7cf162f28d723b6ba7d66aa"},"previous_names":[],"tags_count":79,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stratoscale%2Fskipper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stratoscale%2Fskipper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stratoscale%2Fskipper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stratoscale%2Fskipper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Stratoscale","download_url":"https://codeload.github.com/Stratoscale/skipper/tar.gz/refs/heads/upstream","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243667713,"owners_count":20328032,"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":["docker","git"],"created_at":"2024-07-30T21:01:00.709Z","updated_at":"2025-03-15T00:31:07.545Z","avatar_url":"https://github.com/Stratoscale.png","language":"Python","readme":"# Skipper\n\n## Easily dockerize your Git repository\n\n[![Build Status](https://github.com/Stratoscale/skipper/workflows/build/badge.svg?branch=upstream)](https://github.com/Stratoscale/skipper/actions) [![Release Status](https://github.com/Stratoscale/skipper/workflows/Releases/badge.svg)](https://github.com/Stratoscale/skipper/actions) [![PyPI - Version](https://img.shields.io/pypi/v/strato-skipper?logo=pypi\u0026label=pypi%20package\u0026color=2334D058\u0026cacheSeconds=10)](https://pypi.org/project/strato-skipper)\n\n## Introduction\n\nUse Skipper to build \u0026 test your project in an isolated environment, using Docker containers with pre-defined sane configuration.\nSkipper allows you to execute makefile targets inside a container (or just run arbitrary commands). You can also use Skipper to build your development and production containers.\n\n## Installation\n\nIt is recommended to install Skipper directly from PyPi:\n\n```shell\nsudo pip install strato-skipper\n``` \n\nYou can also install Skipper from source:\n\n``` shell\ngit clone http://github.com/Stratoscale/skipper\nsudo make install\n```\n\nConfigure bash completion for skipper by sourcing the completion script in your ~/.bashrc file:\n\n``` bash\necho 'source \u003c(skipper completion)' \u003e\u003e~/.bashrc\n```\n\n## Python3 Environment\n\nSkipper supports building and running in Python3 environment\nSet your locale to UTF-8:\n\n```shell\nexport LC_ALL=\"en_US.UTF-8\"\nexport LANG=\"en_US.UTF-8\"\n```\n\n## Note for Linux Users with Docker\n\n## Running Skipper on Linux without sudo\n\nIf you are running Skipper on Linux without sudo, Skipper will create a dedicated user inside the build container with both root and docker groups. All commands will be executed on behalf of this user.\n\nTo preserve the environment, Skipper uses the `su` command with the `-m` flag. However, on Debian distros, the PATH variable may be reset even with the `-m` flag specified. To work around this issue, Skipper provides an alternative option using `sudo -sE`.\n\nTo use `sudo -sE` as an alternative:\n\n1. Install `sudo` in the build container.\n2. Disable `env_reset` with `secure_path` in the `/etc/sudoers` defaults.\n3. Set the `SKIPPER_USE_SUDO` environment variable to `\"true\"`.\n\n```shell\nexport SKIPPER_USE_SUDO=\"true\"\n```\n\n```yaml\n# skipper.yaml\n\nenv:\n    SKIPPER_USE_SUDO: \"true\"\n```\n\n**Note:** This information is crucial for a seamless experience when using Skipper with Docker on Linux.\n\n\n## Usage\n\nSkipper can serve as your primary tool for your daily development tasks:\n\n* Use `skipper build` to build the images defined by the Dockerfiles in your repository. All the images will be automatically tagged with the *COMMIT_ID*.\n* Use `skipper push` to publish your images.\n* Use `skipper images` to list your images.\n* Use `skipper rmi` to delete your images.\n* Use `skipper make` to execute makefile targets inside a container.\n* Use `skipper run` to run arbitrary commands inside a container.\n* Use `skipper shell` to get an interactive shell inside a container.\n\n### Global Options\n\n```shell\n  -v, --verbose                 Increase verbosity\n  --registry                    URL of the docker registry\n  --build-container-image       Image to use as build container\n  --build-container-tag         Tag of the build container\n  --build-container-net         Network to connect the build container (default: net=host)\n  --env-file                    Environment variables file/s to pass to the container\n  --build-arg                   Set build-time variables for the container\n  --build-context               Additional build contexts when running the build command, give them a name, and then access them inside a Dockerfile\n  --help                        Show this message and exit.\n```\n\n### [Build context explained](https://www.docker.com/blog/dockerfiles-now-support-multiple-build-contexts/)\n\nSkipper allows you to add additional build contexts when running the build command, give them a name, and then access them inside a Dockerfile.\nThe build context can be one of the following:\n\n* Local directory – e.g. `--build-context project2=../path/to/project2/src`\n* Git repository – e.g. `--build-context qemu-src=https://github.com/qemu/qemu.git`\n* HTTP URL to a tarball – e.g. `--build-context src=https://example.org/releases/src.tar`\n* Docker image – Define with a `docker-image://` prefix, e.g. `--build-context alpine=docker-image://alpine:3.15`\n\nOn the Dockerfile side, you can reference the build context on all commands that accept the “from” parameter. Here’s how that might look:\n\n```dockerfile\nFROM [name]\nCOPY --from=[name] ...\nRUN --mount=from=[name] …\n```\n\n### Build\n\nAs a convention, skipper infers the docker images from the Dockerfiles in the top directory of your repository. For example, assuming that there are 3 Dockerfile in the top directory of the repository:\n\n```\nDockerfile.service1\nDockerfile.service2\nDockerfile.development\n```\n\nTo build the image that corresponeds to `Dockerfile.service1`, run:\n\n```shell\nskipper build service1\n```\n\nIn the same way you can build the image corresponded to `Dockerfile.development`:\n\n```shell\nskipper build development\n```\n\nYou can also build mutliple images with single command:\n\n```shell\nskipper build development service2\n```\n\nA context path can be added to the build command, The build’s context is the files at a specified location PATH, the default is current directory:\n\n```shell\nskipper buid service1 --container-context /path/to/context/dir\n```\n\nIf no image is specifed skipper will build all detected images:\n\n```shell\nskipper build\n```\n\nIf you don't want to store all the Dockerfiles under the top directory of the project, you can specify the project's containers in skipper's config file (see below).\n\n### Push\n\nOnce you've built the images of your repositories as described above. You can publish them by pushing them to the registry.\nTo push the `service1` image, run:\n\n```shell\nskipper --registry some-registry push service1\n```\n\nNote that the registry in this command must be the same registry used while building the image.\n\n### Images\n\nTo list local images of your repository, run:\n\n```shell\nskipper images\n```\n\nIn order to also list also images that were pushed to the registry, run:\n\n```shell\nskipper --registry some-registry images -r\n```\n\n### Rmi\n\nTo delete an image of your repository, run:\n\n```shell\nskipper rmi service1 \u003ctag\u003e\n```\n\nIn order to delete the image from the registry, run:\n\n```shell\nskipper --registry some-registry rmi -r service1 \u003ctag\u003e\n```\n\n### Make\n\nYou can execute a Makefile target inside a container. This is good for keeping the development in an isolated environment, without installing development tools on the host. Once a development container is defined and built, it can be shared among the team member, assuring all of them use exactly thg same development environment.\nAssuming your project has a Makefile with a `tests` target, you can run:\n\n```shell\nskipper --registry some-registry --build-container-image development --build-container-tag latest \\\nmake tests\n```\n\nIf your Makefile is not standard (i.e. `Makefile.arm32`) you can pass it to the make command:\n\n```shell\nskipper --registry some-registry --build-container-image development --build-container-tag latest \\\nmake -f Makefile.arm32 tests\n```\n\n### Run\n\nYou can also run arbitrary commands inside your containers.\n\n```shell\nskipper --registry some-registry --build-container-image development --build-container-tag latest \\\nrun gcc myprog.c -o myprog \n```\n\n### Shell\n\nYou can get a shell inside your containers.\n\n```shell\nskipper --registry some-registry --build-container-image development --build-container-tag latest \\\nshell\n```\n\n## Configuration File\n\nSkipper allows you to define commonly used parameters in a configuration file `skipper.yaml` at the top directory of your repositry.\n\n```yaml\nregistry: some-registry \nbuild-container-image: development\nbuild-container-tag: latest\ncontainer-context: /path/to/context/dir\n\nbuild-arg:\n  - VAR1=value1\n  - VAR2=value2\n\nbuild-context:\n  - context1=/path/to/context/dir # Local directory\n  - qemu-src=https://github.com/qemu/qemu.git # Remote git repository\n  - src=https://example.org/releases/src.tar # Remote tar file\n  - alpine=docker-image://alpine:3.15 # Remote docker image\n\nmake: \n    makefile: Makefile.arm32\ncontainers:\n    service1: path/to/service1/dockerfile\n    service2: path/to/service2/dockerfile\nenv:\n    VAR: value\nenv_file: path/to/env_file.env\n```\n\n```yaml\n# Use the git revision as the build container tag\n# Allows to use the same build container unless the git revision changes\n# This is useful when using a CI system that caches the build container\n# Remember to commit if you changing the build container\nbuild-container-tag: 'git:revision'\n```\n\nUsing the above configuration file, we now can run a simplified version of the make command described above:\n\n```shell\nskipper make tests\n```\n\n### Published ports\n\nFor `shell`, `run` \u0026 `make` commands:  \nBy default, when you run skipper on a linux machine it will use the host network and no mapping required.  \nFor macos and windows machines where the host network is unsupported or for a custom network, you can publish a port and make it available to services outside of the container using the --publish or -p flag.\n\n````shell\nskipper make -p 123:123 tests\nskipper make -p 123-130:123-130 tests\n````\n\n### Environment variables\n\nFor `shell`, `run` \u0026 `make` commands:\nYou can use `-e` in order to pass environment variables to the container.\n\n````shell\nskipper make -e regex=test1 tests\n````\n\nYour configuration file can contain environment variables, Skipper will set the specified environment variables in the container.\n\n````yaml\nenv:\n    VAR: value\n````\n\nYou can add an environment variables file (or multiple files) using `--env-file`.\nThis file should use the syntax \u003ckey\u003e=value (which sets the variable to the given value) or \u003ckey\u003e\n(which takes the value from the local environment), and # for comments.\nThe variables defined in this file will be exported to the container.\nSuch file can look like this:\n\n````shell\n$ cat env_file.env\n# This is a comment\nKEY1=value1\nKEY2=value2\nKEY3    \n````\n\nSkipper configuration file can include the environment variables file:\n\n````yaml\nenv_file: \n    - /path/to/env_file1.env\n    - /path/to/env_file2.env\n````\n\n### Variable substitution\n\nSkipper uses the variable values from the shell environment in which skipper is run.\nIt’s possible to use environment variables in your shell to populate values\nFor example, suppose the shell contains EXTERNAL_PORT=5000 and you supply this configuration:\n\n````yaml\nenv:\n    EXTERNAL_PORT: $EXTERNAL_PORT\n````\n\nWhen you run Skipper command with this configuration, Skipper looks for the EXTERNAL_PORT environment variable in the shell and substitutes its value in.In this example, Skipper resolves the `$EXTERNAL_PORT` to \"5000\" and will set EXTERNAL_PORT=5000 environment in the container.\n\nIf an environment variable is not set, Skipper substitutes with an empty string.\n\nBoth `$VARIABLE` and `${VARIABLE}` syntax are supported. Extended shell-style features, such as `${VARIABLE-default}` and `${VARIABLE/foo/bar}`, are not supported.\n\nYou can use a `$$` (double-dollar sign) when your configuration needs a literal dollar sign. This also prevents Skipper from interpolating a value, so a `$$` allows you to refer to environment variables that you don’t want processed by Skipper.\n\n````yaml\nenv:\n    VAR: $$VAR_NOT_INTERPOLATED\n````\n\n### Shell Interpolation\n\nSkipper supports evaluating shell commands inside its configuration file using `$(command)` notation.\ne.g.\n\n```yaml\nenv:\n    VAR: $(expr ${MY_NUMBER:-5} + 5)\nvolumes:\n    - $(which myprogram):/myprogram\n```\n\n### Volumes\n\nSkipper can bind-mount a host directory into the container.\nyou can add volumes in the configuration file:\n\n````yaml\nvolumes:\n  - /tmp:/tmp:rw\n  - ${HOME}/.netrc:/root/.netrc\n  - ${HOME}/.gocache:/tmp/.gocache\n````\n\n### Workdir\n\nSkipper default to the the project directory as the working directory for the `run`, `make` and `shell` commands,\nyou can override the workdir by specifying it in the configuration file:\n\n````yaml\nworkdir: /path/to/workdir\n````\n\n### Workspace\n\nSkipper default to the the project base directory (e.g. /path/to/project/../) as the workspace for the `run`, `make` and `shell` commands,\nNote that the workspace directory is mounted by default.\nyou can override the workspace directory by specifying it in the configuration file\n\n````yaml\nworkdir: $PWD\n````\n\n### Skipper environment variables\n\nSkipper sets environemnt variables to inform the user about the underline system:\nCONTAINER_RUNTIME_COMMAND - The container conmmand used to run the skipper container. podman/docker\n","funding_links":[],"categories":["Development with Docker","Python"],"sub_categories":["CI/CD"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStratoscale%2Fskipper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FStratoscale%2Fskipper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStratoscale%2Fskipper/lists"}