{"id":18363658,"url":"https://github.com/tritondatacenter/sdc-docker","last_synced_at":"2025-04-12T17:44:09.972Z","repository":{"id":22499352,"uuid":"25838887","full_name":"TritonDataCenter/sdc-docker","owner":"TritonDataCenter","description":"Docker Engine for Triton","archived":false,"fork":false,"pushed_at":"2025-04-03T00:00:26.000Z","size":3463,"stargazers_count":182,"open_issues_count":35,"forks_count":49,"subscribers_count":61,"default_branch":"master","last_synced_at":"2025-04-03T20:11:12.275Z","etag":null,"topics":["docker"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TritonDataCenter.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":"2014-10-27T20:59:24.000Z","updated_at":"2025-03-27T14:42:17.000Z","dependencies_parsed_at":"2024-05-02T01:26:45.594Z","dependency_job_id":"4c24669c-895f-408a-9e16-6a8c90762070","html_url":"https://github.com/TritonDataCenter/sdc-docker","commit_stats":{"total_commits":939,"total_committers":43,"mean_commits":"21.837209302325583","dds":0.7603833865814696,"last_synced_commit":"f7daf7330e90c7f58dfa66cda4ddfc255d7afad3"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TritonDataCenter%2Fsdc-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TritonDataCenter%2Fsdc-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TritonDataCenter%2Fsdc-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TritonDataCenter%2Fsdc-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TritonDataCenter","download_url":"https://codeload.github.com/TritonDataCenter/sdc-docker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248609253,"owners_count":21132877,"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"],"created_at":"2024-11-05T23:07:46.114Z","updated_at":"2025-04-12T17:44:09.936Z","avatar_url":"https://github.com/TritonDataCenter.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\n    This Source Code Form is subject to the terms of the Mozilla Public\n    License, v. 2.0. If a copy of the MPL was not distributed with this\n    file, You can obtain one at http://mozilla.org/MPL/2.0/.\n--\u003e\n\n\u003c!--\n    Copyright 2019 Joyent, Inc.\n    Copyright 2023 MNX Cloud, Inc.\n--\u003e\n\n# sdc-docker\n\nThis repository is part of the Triton Data Center project. See the\n[contribution guidelines](https://github.com/TritonDataCenter/triton/blob/master/CONTRIBUTING.md)\nand general documentation at the main\n[Triton project](https://github.com/TritonDataCenter/triton) page.\n\n`sdc-docker` is the Docker Engine for Triton, where the data center is exposed\nas a single Docker host. The Docker remote API is served from a \"docker\" core\nTriton zone built from this repo.\n\n# User Guide\n\nFor users of the Triton service in a public cloud, or those using\na private Triton Docker stand-up, but not administering it, please see the\n[User Guide](./docs/api/README.md).  The rest of this README is targeted at\n*development* of sdc-docker.\n\n# Docker Version\n\nOffically supported version: 1.21 (equivalent to docker client version 1.9)\n\nSupported version range:\n\n- Remote API: 1.20 to 1.24\n- Docker CLI: 1.8 to 1.12\n- Docker Compose: 1.6 to 1.8\n\nWhen a client makes a remote API call to sdc-docker and it does not specify a\nversion, then sdc-docker will default to the officially supported version.\n\nNewer clients may continue to work, but until we've tested and marked\na newer version as officially supported, then it's best to use an older\nand officially supported version.\n\nDevs: When updating the sdc-docker server official version, you'll need to\nbe sure to update the following:\n\n1. update both *API_VERSION* and *SERVER_VERSION* version in lib/constants.js\n2. update the docker cli test client version in\n   globe-theatre/bin/nightly-test-docker-integration-cli\n\n# Current State\n\nMany commands are currently at least partially implemented. See\n[docs/divergence.md](./docs/api/divergence.md) for details on where sdc-docker\ndiverges from Docker Inc's docker.  This software is under active development\nto provide parity to the newer Docker features that are relevant to SDC, as\nwell as to integrate with other new Triton features .\n\n# Installation\n\nNote: Examples in this section are for\n[CoaL](https://github.com/TritonDataCenter/triton#cloud-on-a-laptop-coal), i.e. some\nsetup will not be appropriate for a production DC.\n\n1. Installing sdc-docker and supporting services:\n\n        ssh root@10.99.99.7                                 # ssh to the CoaL GZ\n        sdcadm self-update\n        sdcadm post-setup common-external-nics \u0026\u0026 sleep 10  # imgapi needs external\n        sdcadm post-setup dev-headnode-prov\n        sdcadm post-setup dev-sample-data  # sample packages for docker containers\n        sdcadm post-setup cloudapi\n        sdcadm post-setup docker\n        sdcadm experimental update dockerlogger\n        # Optional additional steps for VXLAN setup.\n        # TODO: This isn't well automated yet.\n        #    sdcadm post-setup fabrics ...\n        #    \u003creboot\u003e\n\n    For compute nodes added after the first-time setup, you will need to install\n    the dockerlogger on them by executing:\n\n        sdcadm experimental update dockerlogger --servers ${CN1},${CN2},...\n\n    SDC Docker uses (as of [DOCKER-312](https://smartos.org/bugview/DOCKER-312))\n    TLS by default. That means you need to setup a user (or use the 'admin' user)\n    and add an SSH key for access.\n\n2. Create a test user (we'll use \"jill\"):\n\n        # On your dev machine, create a key\n        ssh-keygen -t rsa -m PEM -f ~/.ssh/sdc-docker-jill.id_rsa -b 2048 -N \"\"\n\n        # Copy it to COAL so we can add it to the 'jill' account.\n        scp ~/.ssh/sdc-docker-jill.id_rsa.pub root@10.99.99.7:/var/tmp/\n\n        ssh root@10.99.99.7      # ssh to the CoaL GZ\n        sdc-useradm create -A login=jill email=jill@localhost userpassword=secret123\n        sdc-useradm add-key jill /var/tmp/sdc-docker-jill.id_rsa.pub\n\n3. Generate a client TLS certificate and set `docker` to use `--tls` mode:\n\n    This script in the sdc-docker repo will create the client certificate\n    and print how to configure `docker`:\n\n        ./tools/sdc-docker-setup.sh coal jill ~/.ssh/sdc-docker-jill.id_rsa\n\n    This also puts the env setup in \"~/.sdc/docker/jill/env.sh\".\n\n        source ~/.sdc/docker/jill/env.sh\n\nYou should now able to get `docker info` and see \"SDCAccount: jill\":\n\n    $ docker info\n    Containers: 0\n    Images: 0\n    Storage Driver: sdc\n     SDCAccount: jill\n    Execution Driver: sdc-0.1.0\n    Operating System: SmartDataCenter\n    Name: coal\n\nDocker Compose uses different environment variables across different versions\nto configure timeout. If you receive any warning about the DOCKER_CLIENT_TIMEOUT\nenvironment variable being deprecated, simply unset it and remove it from env.sh.\n\n# Using custom TLS server certificates for SDC Docker\n\nSDC Docker can optionally be setup to use your own TLS certificates. By\ndefault, the Docker VM is provisioned with a self-signed certificate\nthat can always be overridden with the following commands:\n\n        # Copy your TLS certificate to the SDC headnode (assuming COAL)\n        scp ./my-key.pem root@10.99.99.7:/var/tmp/\n        scp ./my-cert.pem root@10.99.99.7:/var/tmp/\n\n        # Install the TLS certificate\n        sdcadm experimental install-docker-cert -k /var/tmp/my-key.pem -c /var/tmp/my-cert.pem\n\nThis command will automatically restart the SDC Docker service so certificate\nchanges will take effect immediately. After changing the TLS certificates, you\nwill need to re-run the ./tools/sdc-docker-setup.sh script.\n\n# Running SDC docker in invite-only mode\n\nThe public APIs to an SDC -- sdc-docker and cloudapi -- can be configured to\nbe in invite-only mode where only explicitly allowed accounts are given\nauthorized. This mode is configured via the `account_allowed_dcs`\n[SDC Application config var](https://github.com/TritonDataCenter/triton/blob/master/docs/operator-guide/configuration.md#sdc-application-configuration).\n\n    sdc-sapi /applications/$(sdc-sapi /applications?name=sdc | json -H 0.uuid) \\\n        -X PUT -d '{\"metadata\": {\"account_allowed_dcs\": true}}'\n    # Optional \"403 Forbidden\" response body.\n    sdc-sapi /applications/$(sdc-sapi /applications?name=sdc | json -H 0.uuid) \\\n        -X PUT -d '{\"metadata\": {\"account_allowed_dcs_msg\": \"talk to your Administrator\"}}'\n\nOnce enabled, one can allow an account via:\n\n    DC=$(sh /lib/sdc/config.sh -json | json datacenter_name)\n    sdc-useradm add-attr LOGIN allowed_dcs $DC\n\nand an account access removed via:\n\n    sdc-useradm delete-attr LOGIN allowed_dcs $DC\n\nAllowed users can be listed via:\n\n    sdc-useradm search allowed_dcs=$DC -o uuid,login,email,allowed_dcs\n\nFor example:\n\n    [root@headnode (coal) ~]# sdc-useradm add-attr admin allowed_dcs coal\n    Added attribute on user 930896af-bf8c-48d4-885c-6573a94b1853 (admin): allowed_dcs=coal\n\n    [root@headnode (coal) ~]# sdc-useradm search allowed_dcs=coal -o uuid,login,email,allowed_dcs\n    UUID                                  LOGIN  EMAIL           ALLOWED_DCS\n    930896af-bf8c-48d4-885c-6573a94b1853  admin  root@localhost  [\"us-west-2\",\"coal\"]\n\n    [root@headnode (coal) ~]# sdc-useradm delete-attr admin allowed_dcs coal\n    Deleted attribute \"allowed_dcs=coal\" from user 930896af-bf8c-48d4-885c-6573a94b1853 (admin)\n\nLimitation: Currently adding access can take a minute or two to take effect\n(caching) and removing access **requires the sdc-docker server to be\nrestarted (DOCKER-233).**\n\n# Adding packages\n\nBy default the size of the container (ram, disk, cpu shares) uses the package in\nthe internal `sdc_` set of packages closest to 'ram=1024 MiB'. The `sdc_`\npackages are really only applicable for development. More appropriate for\nproduction is a set of packages separate from `sdc_`. The following can be\nrun to add a number of `sample-*` packages and to configure the Docker service\nto use them:\n\n    # In the headnode global zone:\n    sdcadm post-setup dev-sample-data\n    /opt/smartdc/bin/sapiadm update \\\n       $(/opt/smartdc/bin/sdc-sapi /services?name=docker | json -H 0.uuid) \\\n       metadata.PACKAGE_PREFIX=\"sample-\"\n\n# Configurations\n\nThe SDC Docker service can be configured with the following Service API\n(SAPI) metadata values.\n\n| Key                            | Type    | Default | Description                                                                  |\n| ------------------------------ | ------- | ------- | ----------- |\n| **USE_TLS**                    | Boolean | false   | Turn on TLS authentication. |\n| **DEFAULT_MEMORY**       | Number | 1024 | The default ram/memory to use for docker containers. |\n| **PACKAGE_PREFIX** | String | 'sample-'    | The prefix for packages to use for docker container package selection. |\n| **USE_FABRICS**          | Boolean | false   | Provision container internal nic on default fabric network. |\n| **ENABLED_LOG_DRIVERS**  | String  | 'json-file,none' | Comma-delimited list of log drivers allowed (see [Log Drivers](./docs/api/features/logdrivers.md)) |\n\nHere is an example of modifying the service configurations with SAPI,\n\n    docker_svc=$(sdc-sapi /services?name=docker | json -Ha uuid)\n    sdc-sapi /services/$docker_svc -X PUT -d '{ \"metadata\": { \"USE_TLS\": true } }'\n\n# Development hooks\n\nBefore commiting be sure to:\n\n    make check      # lint and style checks\n    make test       # run unit tests\n\nA good way to do that is to install the stock pre-commit hook in your\nclone via:\n\n    make git-hooks\n\n# Testing\n\nAs shown above, the run unit tests locally:\n\n    make test\n\nTo run *integration* tests, you need to call the \"test/runtests\" driver from\nthe *global zone* (GZ) of a SmartDataCenter setup with sdc-docker,\ne.g. with COAL that would be:\n\n    ssh root@10.99.99.7\n    /zones/$(vmadm lookup -1 alias=docker0)/root/opt/smartdc/docker/test/runtests\n\nspecifically for COAL there is a target for that:\n\n    make test-integration-in-coal\n\nTo run (a) a particular subset of integration tests -- using 'info' as a filter\non test names in this example -- and (b) with trace-level logging:\n\n    LOG_LEVEL=trace /zones/$(vmadm lookup -1 alias=docker0)/root/opt/smartdc/docker/test/runtests -f info 2\u003e\u00261 | bunyan\n\nSome integration tests (those that don't depend on running in the GZ) can be\nrun from your Mac dev tree, e.g.:\n\n    ./test/runtest ./test/integration/cli-info.test.js\n\nBy default all \"cli\" integration tests (\"test/integration/cli-\\*.test.js\") are\nrun against the latest Docker CLI version (see the\n`DOCKER_AVAILABLE_CLI_VERSIONS` variable in \"test/runtest.common\"). To run\nagainst against other versions, or all supported versions, set the\n`DOCKER_CLI_VERSIONS` (plural) environment variable, e.g.:\n\n    make test-integration-in-coal DOCKER_CLI_VERSIONS=all\n    make test-integration-in-coal DOCKER_CLI_VERSIONS=\"1.11.1 1.10.3\"\n    DOCKER_CLI_VERSIONS=1.11.1 /zones/$(vmadm lookup -1 alias=docker0)/root/opt/smartdc/docker/test/runtests -f cli-info\n    DOCKER_CLI_VERSIONS=latest /zones/$(vmadm lookup -1 alias=docker0)/root/opt/smartdc/docker/test/runtests -f cli-labels\n\n# Testing locally\n\nIt's also possible to run tests directly from your local development machine,\nby specifying the sdc environment and launching node on the test file(s):\n\n    FWAPI_URL=http://10.99.99.26 VMAPI_URL=http://10.99.99.27 node ./test/integration/run-ports.test.js\n\n# Official docker test suite\n\nDocker have their own test suite *integration-cli* for testing a real docker\nenvironment. To run the docker cli tests against coal, you will need a local\ndocker binary and go (golang) installed, then do the following:\n\n    # Target coal\n    export DOCKER_HOST=tcp://my.docker.coal:2376\n    export DOCKER_TEST_HOST=$DOCKER_HOST\n\n    # Set go path, so `go get` works correctly\n    mkdir go \u0026\u0026 cd go\n    export GOPATH=`pwd`\n\n    # Checkout docker from git\n    mkdir -p src/github.com/docker\n    cd src/github.com/docker\n    git clone https://github.com/docker/docker.git\n    cd docker\n\n    # Build docker test infrastructure.\n    sh hack/make/.go-autogen   # docker automated build files\n    # If `go get` shows an error - just ignore it.\n    go get ./...               # docker dependencies\n\n    cd integration-cli\n\n    # Run an individual test\n    go test -test.run \"^TestPsListContainers\"\n\n    # Run all tests - this will take forever... a specific test will be faster.\n    go test -v\n\n# Development from your Mac\n\n1. Add a 'coal' entry to your '~/.ssh/config'. Not required, but we'll use this\n   as a shortcut in examples below.\n\n        Host coal\n            User root\n            Hostname 10.99.99.7\n            ForwardAgent yes\n            StrictHostKeyChecking no\n            UserKnownHostsFile /dev/null\n            ControlMaster no\n\n2. Get a clone on your Mac:\n\n        git clone git@github.com:TritonDataCenter/sdc-docker.git\n        cd sdc-docker\n\n3. Make changes in your local clone:\n\n        vi\n\n4. Sync your changes to your 'docker0' zone in COAL (see\n   [Installation](#installation) above):\n\n        ./tools/rsync-to coal\n\n   This will rsync over changes (excepting binary bits like a change in\n   sdcnode version, or added binary node modules) and restart the docker\n   SMF service.\n\nFor testing I tend to have a shell open tailing the docker service's log file:\n\n    ssh coal\n    sdc-login docker\n    tail -f `svcs -L docker` | bunyan\n\n# Coding style\n\nYou've gotta have one to put to rest some of the bikeshedding. Here's the one\nfor this repo:\n\n- 4-space indentation\n\n- `camelCase` capitalization for variables. This is within reason -- exceptions\n  where case is required due to outside APIs (e.g. Docker APIs) is fine.\n\n- `ClassCase` for classes (i.e. JS prototype'd functions).\n\n- Imports from \"lib/models\" shall consistently be imported as follows to allow\n  grepping for \"Link.list\", etc.\n\n        var ImageTag = require('.../models/image-tag');\n        var Link = require('.../models/link');\n\n## Naming\n\nSome variable/function naming patterns in this repo.\n\n| *Pattern* | *Description* |\n| --------- | ------------- |\n| `req*`    | A restify handler that operates (primarily) on a request and adds a request param. E.g. `reqClientApiVersion` adds `req.clientApiVersion`. |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftritondatacenter%2Fsdc-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftritondatacenter%2Fsdc-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftritondatacenter%2Fsdc-docker/lists"}