{"id":21905970,"url":"https://github.com/frgrisk/river-guide","last_synced_at":"2025-04-15T23:49:01.454Z","repository":{"id":177517233,"uuid":"660500119","full_name":"frgrisk/river-guide","owner":"frgrisk","description":"River-Guide is a simple web interface for managing cloud instances.","archived":false,"fork":false,"pushed_at":"2025-04-01T08:43:07.000Z","size":306,"stargazers_count":2,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-01T09:32:59.377Z","etag":null,"topics":["devops","go"],"latest_commit_sha":null,"homepage":"","language":"Go","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/frgrisk.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":"2023-06-30T06:37:38.000Z","updated_at":"2025-04-01T08:43:09.000Z","dependencies_parsed_at":"2023-07-08T06:17:41.582Z","dependency_job_id":"49d49a1f-aa95-42f0-a4ad-a18112bf66be","html_url":"https://github.com/frgrisk/river-guide","commit_stats":null,"previous_names":["frgrisk/river-guide"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frgrisk%2Friver-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frgrisk%2Friver-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frgrisk%2Friver-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frgrisk%2Friver-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frgrisk","download_url":"https://codeload.github.com/frgrisk/river-guide/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249173061,"owners_count":21224481,"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":["devops","go"],"created_at":"2024-11-28T16:39:39.786Z","updated_at":"2025-04-15T23:49:01.438Z","avatar_url":"https://github.com/frgrisk.png","language":"Go","readme":"# River-Guide\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/frgrisk/river-guide)](https://goreportcard.com/report/github.com/frgrisk/river-guide)\n\nRiver-Guide is a simple web interface for managing cloud instances.\nCurrently, AWS EC2 instances, AWS RDS instances and Azure Virtual Machines are\nsupported. AWS RDS management is turned off by default, but can be enabled by\nsetting the `--rds` flag at application start up.\n\nRiver-Guide utilizes the respective cloud provider's APIs to provide listing\nand start/stop capabilities of instances through a web interface. River-Guide\nalso supports tag-based filtering of instances, enabling you to only display\ninstances of interest. Configuration can be provided through command line\nflags, a configuration file, or environment variables.\n\n![Screenshot 2024-04-03 at 15.36.33.png](cmd/assets/screenshot.png)\n\n## Installation\n\nThe simplest way to get started is using the [pre-built binaries](https://github.com/frgrisk/river-guide/releases).\n\n```bash\nif [[ $(uname -m) == aarch64 ]]; then\n   GOARCH=arm64\nelse\n   GOARCH=amd64\nfi\ncurl -LO https://github.com/frgrisk/river-guide/releases/latest/download/river-guide-linux-$GOARCH\nchmod +x river-guide-linux-$GOARCH\nsudo cp river-guide-linux-$GOARCH /usr/local/bin/river-guide\n```\n\nOr, if you have Go installed, you can install it using Go.\n\n```bash\ngo install github.com/frgrisk/river-guide@latest\n```\n\n## Authentication\n\nFor the application to work, it needs to have the necessary permissions to\nlist, start and stop instances. The application will use the credentials\nconfigured on the machine it's running on. Approaches to authentication\nvary by cloud provider and whether you're temporarily testing\nthe application or deploying it in a production environment.\n\nFor temporary testing, a common pattern is to use the AWS CLI or Azure\nCLI to configure your credentials. For AWS, run `aws configure` and\nprovide your access key and secret key (see [_Get your AWS access keys_](https://aws.github.io/aws-sdk-go-v2/docs/getting-started/#get-your-aws-access-keys)).\nYou can also simply set the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`,\nand `AWS_SESSION_TOKEN` environment variables in your session if you have them.\nFor Azure, you can run `az login` and follow the instructions to authenticate.\n\nFor production deployments, you can use [instance profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html)\nto pass an IAM role for **AWS** or [managed identities](https://learn.microsoft.com/en-us/azure/developer/go/azure-sdk-authentication-managed-identity?tabs=azure-cli)\nfor **Azure**. With either cloud provider, the application will automatically\nuse the credentials configured on the machine it's running on.\n\n### Required Permissions\n\nFor AWS EC2, the following [Amazon EC2 permissions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_Operations.html)\nare required:\n\n- `ec2:DescribeInstances`\n- `ec2:StartInstances`\n- `ec2:StopInstances`\n- `ec2:DescribeInstanceStatus`\n\nFor AWS RDS, the following [Amazon RDS permissions](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_Operations.html)\nare required:\n\n- `rds:DescribeDBInstances`\n- `rds:StartDBInstance`\n- `rds:StopDBInstance`\n\nFor Azure, the following [Microsoft.Compute permissions](https://learn.microsoft.com/en-us/azure/role-based-access-control/permissions/compute#microsoftcompute)\nare required:\n\n- `Microsoft.Compute/virtualMachines/read`\n- `Microsoft.Compute/virtualMachines/instanceView/read`\n- `Microsoft.Compute/virtualMachines/start/action`\n- `Microsoft.Compute/virtualMachines/deallocate/action`\n\n## Usage\n\n### Examples\n\nThis section includes examples of how to use the application. See the\n[Flags](#flags) section for a complete list of flags.\n\nStart the server with the default settings, which will listen on port 3000 and\nuse AWS as the cloud provider, and display all instances.\n\n```bash\nriver-guide\n```\n\nStart the server with RDS support enabled.\n\n```bash\nriver-guide --rds\n```\n\nStart the server with a custom port and title.\n\n```bash\nriver-guide --port 8080 --title \"My Custom Title\"\n```\n\nQuery instances in a different region and filter on instances that have both tag\nkey \"Environment\" and value \"dev\" and tag key \"DashboardManageable\" and value\n\"true\".\n\n```bash\nAWS_REGION=us-west-2 river-guide --tags \"Environment=dev,DashboardManageable=true\"\n```\n\nUse the Azure cloud provider and filter on instances in the \"my-resource-group\"\nresource group having both tag key \"Environment\" and value \"dev\" and tag key\n\"DashboardManageable\" and value \"true\".\n\n```bash\nriver-guide --provider azure \\\n            --tags \"Environment=dev,DashboardManageable=true\" \\\n            --resource-group-name \"my-resource-group\" \\\n            --subscription-id \"00000000-0000-0000-0000-000000000000\"\n```\n\n### Flags\n\nThe application accepts several flags:\n\n- `--config`: path to configuration file (default is `$HOME/.river-guide.yaml`).\n- `-p, --port`: port to listen on (default is `3000`).\n- `--path-prefix`: path prefix for the application (default is `/`). This\n  can be useful when running the application behind a reverse proxy.\n- `--provider`: cloud provider to use (default is `aws`).\n- `--resource-group-name`: filter instances based on their resource group membership\n  (only used with the Azure provider).\n- `--subscription-id`: subscription ID to use (required for Azure).\n- `-t, --tags`: filter instances using tag key-value pairs (e.g.,\n  `Environment=dev,Name=dev.example.com`).\n- `--title`: title to display on the web page (default is \"Environment\n  Control\").\n- `--primary-color`: primary color for text (default is \"#333\").\n- `--favicon`: path to favicon (default is embedded favicon).\n- `--rds`: enable support to control RDS instances (default is `false`).\n\n### Configuration file\n\nThe application can also use a configuration file for setting the parameters.\nThe configuration file should be in the YAML format. By default, the\napplication will look for a `.river-guide.yaml` file in the home directory.\nThe structure of the file should look something like this:\n\n```yaml\nport: 3000\ntags:\n  Environment: dev\n  Name: dev.example.com\ntitle: Environment Control\nprimary-color: \"#333\"\nfavicon: \"/path/to/favicon\"\n```\n\n### Environment variables\n\nIn addition to flags and the configuration file, you can also use\nenvironment variables to set parameters. The application will automatically\nlook for any environment variables beginning with `RIVER_GUIDE_`. For\ninstance, to set the title, you could use the following command:\n\n```bash\nexport RIVER_GUIDE_TITLE=\"My Custom Title\"\n```\n\n## API\n\nThe application provides the following endpoints:\n\n- `GET /`: The main interface for managing AWS EC2 instances.\n- `GET /favicon.ico`: Endpoint for serving favicon.\n- `POST /toggle`: Endpoint for toggling the start/stop state of all instances.\n\n## To Do\n\n- [ ] Add error handling for AWS API calls.\n\n## License\n\nRiver Guide is released under the MIT License. See the [LICENSE](./LICENSE)\nfile for more details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrgrisk%2Friver-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrgrisk%2Friver-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrgrisk%2Friver-guide/lists"}