{"id":21040189,"url":"https://github.com/p-t-i/spectacles","last_synced_at":"2026-03-08T05:31:59.207Z","repository":{"id":39258889,"uuid":"340132747","full_name":"P-T-I/spectacles","owner":"P-T-I","description":"Gui for docker hub registry","archived":false,"fork":false,"pushed_at":"2025-07-14T13:42:38.000Z","size":12037,"stargazers_count":1,"open_issues_count":43,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-14T17:35:31.831Z","etag":null,"topics":["docker","docker-image","flask","flask-application"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/P-T-I.png","metadata":{"files":{"readme":"README.rst","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,"zenodo":null}},"created_at":"2021-02-18T17:55:16.000Z","updated_at":"2021-11-11T19:11:15.000Z","dependencies_parsed_at":"2023-02-09T02:31:17.596Z","dependency_job_id":"f2796d33-c749-415f-b735-425ba3eb1268","html_url":"https://github.com/P-T-I/spectacles","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/P-T-I/spectacles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P-T-I%2Fspectacles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P-T-I%2Fspectacles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P-T-I%2Fspectacles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P-T-I%2Fspectacles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/P-T-I","download_url":"https://codeload.github.com/P-T-I/spectacles/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/P-T-I%2Fspectacles/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30246724,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T00:58:18.660Z","status":"online","status_checked_at":"2026-03-08T02:00:06.215Z","response_time":56,"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":["docker","docker-image","flask","flask-application"],"created_at":"2024-11-19T13:45:09.324Z","updated_at":"2026-03-08T05:31:59.186Z","avatar_url":"https://github.com/P-T-I.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. image:: images/spectacles_text.png\n\n.. Everything after the include marker below is inserted into the sphinx html docs. Everything above this comment is\n   only visible in the github README.rst\n   ##INCLUDE_MARKER##\n\n.. image:: https://img.shields.io/github/release/P-T-I/spectacles.svg\n   :target: https://GitHub.com/P-T-I/spectacles/releases/\n\n.. image:: https://img.shields.io/badge/License-GPLv3-blue.svg\n   :target: https://www.gnu.org/licenses/gpl-3.0\n\n.. image:: https://badgen.net/badge/Github/repo/green?icon=github\n   :target: https://GitHub.com/P-T-I/spectacles\n\nSpectacles is a docker image which can be used to act as an authorization server for docker v2 registries. It provides\na web interface to allow you full control over the available repositories in your private registry. Spectacles has a\nfine grained user management system and allows these user READ, WRITE or FULL access to repositories via the use of\nfully configurable namespaces.\n\nDatabase support\n----------------\nSpectacles can be used with different sql databases and has been tested with sqllite and mysql as database backends.\nIn order to fully make use of the functionalities of spectacles; an external mysql instance is highly advised.\n\nThis is because a local sqllite database will (for the moment) limit spectacles ability to fetch updates from the\nregistry via a (second spectacles instance) background process and fully persist spectacles state.\nSee `Configuring spectacles`_ for more details.\n\nConfiguring spectacles\n----------------------\n\nAs mentioned in the previous paragraph spectacles needs 2 containers in order to be fully functional; 1 for the webserver\nand 1 for a background process. The webserver container is the default with which the image is build and handles all\ngui related actions and inputs. The background container is responsible for periodically contacting the registry and\nupdating the repository tag entries in the database. In order to activate the background process the command for the\nspectacles image need to be overwritten with ``[\"runbackground\"]``. As shown in the docker-compose_EXAMPLE.yml\nfile.\n\nData Persistence\n================\n\nAll data that should be able to survive a container rebuild/restart (like avatars, logs, registry certs, and sqllite\ndatabase) is saved by spectacles in the `/app/data` folder inside the container. So a volume should be mounted from\nthe host to the `/app/data` folder. As shown in the docker-compose_EXAMPLE.yml file.\n\nSetup TLS for spectacles webserver\n==================================\n\nBy default spectacles will run a HTTP webserver; if you would like to use a HTTPS webserver then mount an additional\nvolume containing the key en certificate (in pem format) into the container and set the environment variables\n``SPECTACLES_WEB_TLS_KEY_PATH`` and ``SPECTACLES_WEB_TLS_CERT_PATH`` accordingly.\n\nEnvironment variables\n=====================\n\n- ``DB_HOST`` (default: *mysql*): IP-address or FQDN of the MYSQL database;\n- ``DB_BACKEND`` (default: *mysql*): Select which backend you would like to use for spectacles. Choices are 'mysql' or\n  'other';\n- ``SQLALCHEMY_DATABASE_URI`` (default: *sqlite:////app/data/db/spectacles.db*): The database URI that should be used\n  for the connection. Examples:\n\n  - sqlite:////tmp/test.db\n  - mysql://username:password@server/db\n\n- ``AVATARS_SAVE_PATH`` (default: */app/data/avatars/*): Path where to store the avatars created for spectacles users;\n- ``SPECTACLES_PRIV_KEY_PATH`` (default: */app/data/certs/domain.key*): Path to where the private key used by the\n  registry to validate the created tokens from spectacles. This should be the same key that is created in the paragraph\n  `Configuring registry`_ and set to the environment variable ``REGISTRY_HTTP_TLS_KEY`` of the docker registry image;\n- ``SPECTACLES_ISSUER_NAME`` (default: *Auth service*): Name you wish to give to the spectacles instance. Should be set\n  to the same value as the environment variable ``REGISTRY_AUTH_TOKEN_ISSUER`` of the docker registry image;\n- ``SPECTACLES_BACKGROUND_UPDATE`` (default: *30*): Specify the interval for the background process in seconds. 30 in\n  this example makes sure that the background process runs every 30 seconds;\n- ``SPECTACLES_WEB_TLS_KEY_PATH`` (default: */app/certs/key.pem*): Path to the TLS key for the HTTPS webserver;\n- ``SPECTACLES_WEB_TLS_CERT_PATH`` (default: */app/certs/cert.pem*): Path to the TLS certificate for the HTTPS webserver;\n- ``OPENID_LOGIN`` (default: *False*): Whether to use an openid provider for logging into spectacles;\n- ``SQL_DEBUG_LOGGING`` (default: *False*): If enabled all queries to the database are logged for debug purposes;\n- ``LOG_FILE_PATH`` (default: */app/data/log/*): Directory where to store the logging;\n- ``LOG_FILE_NAME`` (default: *spectacles.log*): Filename of the logging;\n- ``SYSLOG_ENABLE`` (default: *False*): Whether to enable logging to a syslog server;\n- ``SYSLOG_SERVER`` (default: *172.16.1.1*): IP address or FQDN of the syslog server;\n- ``SYSLOG_PORT`` (default: *5140*): UDP port of the syslog server;\n\nConfiguring registry\n--------------------\n\nThe registry that can be used for spectacles is a normal `docker registry \u003chttps://hub.docker.com/_/registry\u003e`_ and\nfurther details and settings about that image is listed there.\n\nHowever for simplicity sake here is an example of the environment settings that should be set on the image:\n   - REGISTRY_STORAGE_DELETE_ENABLED=true\n   - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/mnt/registry/data\n   - REGISTRY_AUTH=token\n   - REGISTRY_AUTH_TOKEN_REALM=https://localhost:5050/token_auth\n   - REGISTRY_AUTH_TOKEN_SERVICE=\"Docker registry\"\n   - REGISTRY_AUTH_TOKEN_ISSUER=\"Auth service\"\n   - REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE=/mnt/local/certs/domain.crt\n   - REGISTRY_HTTP_TLS_CERTIFICATE=/mnt/local/certs/domain.crt\n   - REGISTRY_HTTP_TLS_KEY=/mnt/local/certs/domain.key\n\nCouple of pointers:\n\n- the ``REGISTRY_STORAGE_DELETE_ENABLED`` variable controls whether or not the registry let's you 'delete' a\n  repository / tag.\n  Please keep in mind that, although the repository / tag seems deleted, it's not really gone until you run the registry's\n  garbage collector. More details in the `documentation \u003chttps://docs.docker.com/registry/\u003e`_;\n- the ``REGISTRY_AUTH_TOKEN_REALM`` should be set to the IP address / FQDN of the spectacles webserver and should point\n  to the token_auth endpoint;\n- the ``REGISTRY_AUTH_TOKEN_ISSUER`` should be set to the same value as ``SPECTACLES_ISSUER_NAME`` from the previous\n  paragraph;\n- the ``REGISTRY_HTTP_TLS_KEY`` should be set to the path to the registry's private key and should be set to the same\n  key as ``SPECTACLES_PRIV_KEY_PATH``. The private key can be created via the command:\n\n   openssl req -newkey rsa:4096 -nodes -keyout domain.key -out domain.csr -subj '/C=XX/ST=XX/L=XXXX/O=Docker\n   Registry/CN=example.docker.reg'\n\n- the ``REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE`` and the ``REGISTRY_HTTP_TLS_CERTIFICATE`` should be set to the path of the\n  registry's signed certificate. The certificate can be created / signed via the command:\n\n   openssl x509 -signkey domain.key -in domain.csr -req -days 3650 -out domain.crt\n\n- if you would like to persist the registry's data you should mount a volume to the /mnt/registry/data;\n- the certificate and key created earlier should be mounted into the /mnt/local/certs.\n\nQuick start\n-----------\n\nThe easiest way to quickly setup a full suite is to use the provided docker-compose_EXAMPLE.yml. Once that file is\ntweaked to your specifications all steps below assume that you've renamed the docker-compose_EXAMPLE.yml to\ndocker-compose.yml; if that's not the case you should specify the file with a -f flag appended to the docker-compose\ncommand.\n\nThese steps can be read in the full `documentation \u003chttps://p-t-i.github.io/spectacles/\u003e`_ (NOT COMPLETED YET);\n\nStart all containers:\n\n   docker-compose up\n\nOnce the containers are up and running; navigate to http(s)://localhost:5050 and register your first user. (The first\nregistered user will automatically be made an administrative user.)\n\nOnce logged-in navigate to the 'Registries' page and add your first registry.\n\nOnce successful add a namespace to the registry you've just configured by navigating to the namespaces page and create\nthe namespace 'test'.\n\nNow your set to login to your registry and push your first repository.\n\nFrom the command line (assuming your registry runs on the default port of 5000):\n\n   docker login localhost:5000\n\nIt will request your username and password (from the admin user you've just created within spectacles) and will report\nback when the login is successful.\n\nNow pull a image from the public docker hub and tag it for our private repository:\n\n   docker pull hello-world\n   \n   docker tag hello-world:latest localhost:5000/test/hello-world:latest\n\nPush the image to the private repo:\n\n   docker push localhost:5000/test/hello-world:latest\n\nOnce the sheduled background process has completed it will show up within spectacles.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp-t-i%2Fspectacles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fp-t-i%2Fspectacles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp-t-i%2Fspectacles/lists"}