{"id":17922475,"url":"https://github.com/pthorpe92/floundr","last_synced_at":"2025-03-24T02:32:32.648Z","repository":{"id":253590619,"uuid":"831701119","full_name":"PThorpe92/Floundr","owner":"PThorpe92","description":"Container Registry built with Axum/Tokio + Registry mgmt TUI client built with Ratatui","archived":false,"fork":false,"pushed_at":"2024-09-10T01:25:50.000Z","size":1062,"stargazers_count":16,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-17T15:15:27.394Z","etag":null,"topics":["axum","containers","distribution","docker","oci","ratatui","rust","tui"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PThorpe92.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2024-07-21T11:21:45.000Z","updated_at":"2025-02-27T18:48:06.000Z","dependencies_parsed_at":"2024-08-18T00:30:37.843Z","dependency_job_id":"2985ecb8-cb10-4709-91e5-99f1eb697b31","html_url":"https://github.com/PThorpe92/Floundr","commit_stats":null,"previous_names":["pthorpe92/floundr"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PThorpe92%2FFloundr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PThorpe92%2FFloundr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PThorpe92%2FFloundr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PThorpe92%2FFloundr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PThorpe92","download_url":"https://codeload.github.com/PThorpe92/Floundr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245198719,"owners_count":20576424,"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":["axum","containers","distribution","docker","oci","ratatui","rust","tui"],"created_at":"2024-10-28T20:39:21.486Z","updated_at":"2025-03-24T02:32:32.262Z","avatar_url":"https://github.com/PThorpe92.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Floundr: OCI Container Registry + TUI Client\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"config/logo.png\" alt=\"logo\" width=\"160\" /\u003e\n\u003c/div\u003e\n\n**Floundr** is a _WIP_ container registry written in Rust with Axum, and an accompanying TUI client built with [Ratatui](https://github.com/ratatui-org/ratatui)\nThe eventual goal is a registry designed to be simple, efficient, and easy to manage, aiming to be fully compliant with\nthe OCI distribution spec.\n\n## Current State | Existing Features\n\nThis project is in active development and is not fully OCI compliant at this time. The following features\nexist in the project in some form but are not fully implemented or tested, it is not recommended for production use.\n\n- **Authentication:** `docker login`, with basic and bearer authentication and scoped tokens.\n- **User Management**: Limited user management in the TUI client.\n- **Basic Docker Push/Pull:** basic `docker push | pull` commands are supported.\n- **TUI Client:** _WIP_ Manage the registry through a terminal-based interface built with Ratatui.\n- **Storage Backend:** Local storage is currently supported (Tokio async I/O)\n- **SSL/TLS:** Serves over https with Rustls, with http redirect.\n\n## Roadmap | TODO\n\n- **Complete Specification Compliance**: Finish endpoints to be fully compliant with the OCI distribution spec.\n- **Complete User Roles and Permissions**: Add/Edit Scopes for each User or API key in the client.\n- **S3 Storage Driver**: Add support for S3 storage backend + decouple disk persistence from the DB layer.\n- **Garbage Collection**: Run garbage collection to remove ref-counted unused layers on a schedule.\n\n## Installation\n\nTo get started with Floundr, you'll need to have Rust installed on your system. You can install Rust using [rustup](https://rustup.rs/).\n\n1. Clone the repository:\n\n   ```sh\n   git clone https://github.com/PThorpe92/floundr.git\n   cd floundr\n   ```\n\n2. Build the project:\n\n   ```sh\n   cargo build --release\n   ```\n\n3. Set the `FLOUNDR_HOME` \u0026 `DB_PATH` environment variables in your .env file:\n\n   ```sh\n   FLOUNDR_HOME=/path/to/your/storage\n   DB_PATH=/path/to/your/db\n   APP_URL=localhost:8080\n   JWT_SECRET_KEY=your_secret_key\n   HOST=host\n   PORT=port\n\n   # for development, you will need to set the following\n   export APP_URL=debug\n   export DATABASE_URL=sqlite://path/to/your/db\n   ```\n\n4. Run the commands to create a new repository and user:\n\n```sh\n./target/release/floundr new-repo \u003cmy-repo\u003e --public\n\n./target/release/floundr new-user \u003cemail\u003e --password \u003cpassword\u003e\n```\n\n6. Compile and Run the TUI client\n\n```sh\ncd tui_client \u0026\u0026 cargo run --release\n```\n\n7. The client will write a `floundr.yml` file to the value of your `FLOUNDR_HOME` environment variable\n   It will have the default email + password, which you can swap out for the ones you created.\n   Optionally, you can also create a new API key with the `gen-key \u003cfile\u003e` flag and it will write the key to\n   the file you specify. Be aware that API keys hold full scope to all repositories, and if logging in with\n   `docker login`, it will only request the scope needed for the operation.\n\nRun --help for all options\n\n\n```sh\nUsage: floundr [OPTIONS] [COMMAND]\n\nCommands:\n  migrate-fresh  Migrate the database to a fresh state\n  new-repo       Create a new repository with the given name\n  new-user       Create a new user with the given email\n  gen-key        Generate a new API key for a user with administrative privileges\n  help           Print this message or the help of the given subcommand(s)\n\nOptions:\n  -p, --port \u003cPORT\u003e                    [default: 8080]\n      --storage-path \u003cSTORAGE_PATH\u003e\n      --home-dir \u003cCONTAINER_HOME_DIR\u003e  path to the floundr home directory (default is $XDG_DATA_HOME/floundr)\n      --ssl                            enable https\n      --cert-path \u003cCERT_PATH\u003e          path to the certificate file\n      --key-path \u003cKEY_PATH\u003e            path to the private key file\n      --https-port \u003cHTTPS_PORT\u003e        port to serve tls on [default: 443]\n  -d, --db-path \u003cDB_PATH\u003e              path to the sqlite database\n      --driver \u003cDRIVER\u003e                [default: local] (TODO s3)\n      --debug                          Enable debug mode\n  -h, --help                           Print help\n  -V, --version                        Print version\n```\n\n### TUI Client\n\nThe TUI client provides a straightforward interface for managing your images and repositories.\nManage users, repositories and API keys with vim keybindings.\n\n\u003cimg src=\"config/tui_client.png\" alt=\"TUI Client\" width=\"600\"/\u003e\n\n\u003cimg src=\"config/tui_client_users.png\" alt=\"TUI Client\" width=\"600\"/\u003e\n\n\u003cimg src=\"config/tui_client_repos.png\" alt=\"TUI Client\" width=\"600\"/\u003e\n\n\u003cimg src=\"config/tui_client_keys.png\" alt=\"TUI Client\" width=\"600\"/\u003e\n\n\u003cimg src=\"config/tui_client_create_key.png\" alt=\"TUI Client\" width=\"600\"/\u003e\n\n\n\n\n## Should I use this in production?\n\nNo it is not ready for any kind of production use.\n\n\n## Contributing\n\nContributions are very welcome! Lots of low hanging fruit, this was open sourced earlier than I would have preferred because I have limited time to work on it. Please feel free to submit issues, feature requests, or pull requests.\n\n## License\n\nFloundr is released under the MIT License. See the [LICENSE](LICENSE) file for more details.\n\n## Why?\n\nPart RWIIR (re-write it in rust) syndrome, part any reason to use [ratatui](https://github.com/ratatui-org/ratatui)\n\n## **Fun fact:**\n\n\u003e This project was developed in the Maine State Prison system, where the author is currently incarcerated. I would like to bring whatever awareness possible to the importance of education and rehabilitation for those 2.2 million Americans currently incarcerated. I have a [blog post](https://pthorpe92.dev/intro/my-story/) if you are interested in reading about my story.\n\nFor any questions, please open an issue or reach out to [preston@pthorpe92.dev](mailto:preston@pthorpe92.dev).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpthorpe92%2Ffloundr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpthorpe92%2Ffloundr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpthorpe92%2Ffloundr/lists"}