<p align="center">
<img src="logo.png" alt="Gorunn Logo">
</p>
**Gorunn** is a powerful CLI tool for managing local development environments with Docker. It provides a streamlined way to manage multiple projects, handle environment configurations, and orchestrate various services.
Website: https://gorunn.io
## Minimum Requirements:
- Python 3.10+
- [Pipx](https://github.com/pypa/pipx)
- Docker and Docker Compose
- OS:
- MacOS (Tested on Sequoia 15.0.1)
- Ubuntu (tested on 24.04)
## Supported languages
- Python
- Node.js / Next.js
- PHP
## Installation
```bash
pipx install gorunn
```
## Quick Start
### Initialize the stack
1. Prepare project manifest by following the [example](https://github.com/parapidcom/gorunn-project-manifests) structure.
2. Initialize the stack and follow the prompts:
```bash
gorunn init
```
When you run gorunn init, you'll be prompted to configure:
- **Stack name** (default: **gorunn**). This will be used as a prefix for all the services.
- **Projects repository URL** (optional). If you have one.
- **Projects local path**. This is where your project manifests will be stored.
- **Workspace path**. This is where your application local directory will be created or cloned.
- **Docker network subnet**. This is the subnet for the Docker network. Leave empty to use default if you don't know what it is, change only in case you have conflict with your existing docker compose network subnet.
- **Service selection** (MySQL, Postgres, Redis, Memcached, Kafka, Chroma, OpenSearch,RabbitMQ, MongoDB). These are the services you want to use.
- **Encryption key for environment variables**. This is the key used to encrypt your environment variables so that you can safely push them to repo together with project manifests.
- **Aider AI assistant**. You will be prompted to enable [Aider](https://aider.chat) AI assistant for your project. If you want to use it, prepare your OpenAI API or Anthropic API key.
You can specify project manifest directory as an option:
```bash
gorunn init --parse --import /path/to/your/projects-manifests
```
or you can specify project manifest repository URL if you have one:
```bash
gorunn init --parse --import git@github.com:yourorg/projects-manifests.git
```
#### Example Stack
Optionally you can use our example project stack with `react`, `laravel` and `django` projects:
```bash
gorunn init --import https://github.com/parapidcom/gorunn-project-manifests.git
```
### Parse the project manifests
```bash
gorunn parse
```
### Build the projects
This command will iterate over build_commands defined in the project manifests and run them inside containers.
You can build all projects:
```bash
gorunn build --app all
```
or specific one:
```bash
gorunn build --app myapp
```
## Configuration
### Main configuration
#### Location
```
$HOME/.config/gorunn/
├── config.yaml # Main configuration generated by `gorunn init`
```
#### Structure
```yaml
aider: (enable Aider AI assistant for the stack)
api_key: your_llm_api_key
enabled: true|false
llm: OpenAI|Claude
services: (enable one or more services for the stack)
chroma: true|false
mysql: true|false
opensearch: true|false
postgres: true|false
redis: true|false
kafka: true|false
memcached: true|false
rabbitmq: true|false
mongo: true|false
docker_compose_subnet: 10.10.0.0/16 (leave as is if you don't know what it is)
encryption_key: generated by `gorunn init` on first run
projects:
path: /absolute/path/to/projects/manifests (default: $HOME/gorunn/projects)
repo_url: git@github.com:parapidcom/gorunn-project-manifests.git (repo to your project manifests, defining local stack)
stack_name: stack_name (default: gorunn) - no spaces or special characters, lowercase. This will be used as a prefix for all the services.
workspace_path: /absolute/path/to/workspace (default: $HOME/gorunn/workspace) - this is where your project local directories will be created or cloned
```
### Project Manifests and Environment files
A project manifest in **Gorunn** is a YAML file that defines the configuration for a project that is part of the stack. Example can be found in the [example stack](https://github.com/parapidcom/gorunn-project-manifests).
#### Location
```
$HOME/gorunn/
├── myreact.yaml # Project manifest for the myreact app
├── mydjango.yaml # Project manifest for the mydjango app
├── env/
├─── myreact.env # Environment files for the myreact app
├─── mydjango.env # Environment files for the mydjango app
```
#### Structure
- **git_repo**: git@github.com:parapidcom/gorunn-example-react (git repository url of the project)
- **type**: node (type of the project, one of: node, php, python)
- **version**: "20" (version of the platform being used, e.g. node version, php version, python version)
- **endpoint**: myreact.local.gorunn.io (optional, if defined, the CLI will create a virtual host on the local proxy for it. The endpoint must be in the form of `%s.local.gorunn.io`)
- **env_vars**: true (boolean, if true, the CLI will load it from manifests directory (if it does not exist, it will create a new file from a template))
- **start_command**: npm run dev (command used to start the server)
- **listen_port**: 3000 (port on which your local server will listen, allowing the proxy to forward to it as upstream)
- **build_commands**: (list of commands necessary for project bootstrap. These are called with the `gorunn build --app app_name` command)
## Project Manifests and Environment Files Location
Project manifests locations defaults to `$HOME/gorunn/projects/` during `gorunn init`.
Can be manually changed in the main configuration file.
### Environment Variables
Environment files are part of the project manifests directory structure. They are stored in `env/` subdir of the project manifests directory.
#### Encrypt an environment file
```bash
gorunn projects env --encrypt --app myapp
```
#### Decrypt an environment file
```bash
gorunn projects env --decrypt --app myapp
```
### Project Management Commands
#### Pull latest project manifests from remote repository
```bash
gorunn projects pull
```
#### Push project manifests and environment files changes to remote repository
```bash
gorunn projects publish
```
#### Show stack projects information
```bash
gorunn info
```
### Build Commands
#### Build all projects defined in the project manifests directory
```bash
gorunn build --app all
```
#### Build specific project
```bash
gorunn build --app myapp
```
### Container Management
#### Start containers
```bash
gorunn start [--app APP_NAME]
```
#### Stop containers
```bash
gorunn stop [--app APP_NAME]
```
#### Restart containers
```bash
gorunn restart [--app APP_NAME]
```
#### Stream logs
```bash
gorunn logs [--app APP_NAME] [--follow]
```
#### Access terminal
```bash
gorunn terminal --app APP_NAME
```
#### Aider AI assistant
You can use [Aider](https://aider.chat) to help you with your project if you have enabled it and provided your LLM API key.
```bash
gorunn aider --app APP_NAME --browser
```
This will start Aider in browser mode and you can use it to help you code in browser on http://localhost:8501
### Info
Print information about the stack.
```bash
gorunn info
```
### Version
Print currently installed **Gorunn** version.
```bash
gorunn version
```
#### Trust
On MacOS, you can add the **Gorunn**'s self signed certificate for `*.local.gorunn.io domain` to keychain.
It is done automatically during `gorunn init`.
```bash
gorunn trust
```
## Best Practices
### Project Manifests
- Keep manifests in version control
- Use consistent naming conventions
### Environment Variables
- Always use encryption for sensitive data
- Keep backup of encryption keys
- Use separate env files per environment
### Resource Management
- Stop unused services to free resources
- Regular cleanup using gorunn destroy
- Monitor container logs for issues
Raw data
{
"_id": null,
"home_page": "https://github.com/parapidcom/gorunn",
"name": "gorunn",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Goran Parapid",
"author_email": "goran@parapid.com",
"download_url": "https://files.pythonhosted.org/packages/4c/56/d55a2fbfe718954742a1a9a4d8541edda78df9e0b950dff21a305e52f69e/gorunn-0.0.11.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"logo.png\" alt=\"Gorunn Logo\">\n</p>\n\n**Gorunn** is a powerful CLI tool for managing local development environments with Docker. It provides a streamlined way to manage multiple projects, handle environment configurations, and orchestrate various services.\n\n\nWebsite: https://gorunn.io\n\n## Minimum Requirements:\n- Python 3.10+\n- [Pipx](https://github.com/pypa/pipx)\n- Docker and Docker Compose\n- OS:\n - MacOS (Tested on Sequoia 15.0.1)\n - Ubuntu (tested on 24.04)\n\n## Supported languages\n- Python\n- Node.js / Next.js\n- PHP\n\n## Installation\n\n```bash\npipx install gorunn\n```\n\n## Quick Start\n\n### Initialize the stack\n1. Prepare project manifest by following the [example](https://github.com/parapidcom/gorunn-project-manifests) structure.\n\n2. Initialize the stack and follow the prompts:\n```bash\ngorunn init\n```\n\nWhen you run gorunn init, you'll be prompted to configure:\n- **Stack name** (default: **gorunn**). This will be used as a prefix for all the services.\n- **Projects repository URL** (optional). If you have one.\n- **Projects local path**. This is where your project manifests will be stored.\n- **Workspace path**. This is where your application local directory will be created or cloned.\n- **Docker network subnet**. This is the subnet for the Docker network. Leave empty to use default if you don't know what it is, change only in case you have conflict with your existing docker compose network subnet.\n- **Service selection** (MySQL, Postgres, Redis, Memcached, Kafka, Chroma, OpenSearch,RabbitMQ, MongoDB). These are the services you want to use.\n- **Encryption key for environment variables**. This is the key used to encrypt your environment variables so that you can safely push them to repo together with project manifests.\n- **Aider AI assistant**. You will be prompted to enable [Aider](https://aider.chat) AI assistant for your project. If you want to use it, prepare your OpenAI API or Anthropic API key.\nYou can specify project manifest directory as an option:\n\n```bash\ngorunn init --parse --import /path/to/your/projects-manifests\n```\n\nor you can specify project manifest repository URL if you have one:\n\n```bash\ngorunn init --parse --import git@github.com:yourorg/projects-manifests.git\n```\n\n#### Example Stack\nOptionally you can use our example project stack with `react`, `laravel` and `django` projects:\n```bash\ngorunn init --import https://github.com/parapidcom/gorunn-project-manifests.git\n```\n### Parse the project manifests\n```bash\ngorunn parse\n```\n### Build the projects\nThis command will iterate over build_commands defined in the project manifests and run them inside containers.\nYou can build all projects:\n```bash\ngorunn build --app all\n```\n\nor specific one:\n\n```bash\ngorunn build --app myapp\n```\n\n## Configuration\n\n### Main configuration\n\n#### Location\n```\n$HOME/.config/gorunn/\n\u251c\u2500\u2500 config.yaml # Main configuration generated by `gorunn init`\n```\n#### Structure\n```yaml\naider: (enable Aider AI assistant for the stack)\n api_key: your_llm_api_key\n enabled: true|false\n llm: OpenAI|Claude\nservices: (enable one or more services for the stack)\n chroma: true|false\n mysql: true|false\n opensearch: true|false\n postgres: true|false\n redis: true|false\n kafka: true|false\n memcached: true|false\n rabbitmq: true|false\n mongo: true|false\ndocker_compose_subnet: 10.10.0.0/16 (leave as is if you don't know what it is)\nencryption_key: generated by `gorunn init` on first run\nprojects:\n path: /absolute/path/to/projects/manifests (default: $HOME/gorunn/projects)\n repo_url: git@github.com:parapidcom/gorunn-project-manifests.git (repo to your project manifests, defining local stack)\nstack_name: stack_name (default: gorunn) - no spaces or special characters, lowercase. This will be used as a prefix for all the services.\nworkspace_path: /absolute/path/to/workspace (default: $HOME/gorunn/workspace) - this is where your project local directories will be created or cloned\n```\n\n### Project Manifests and Environment files\nA project manifest in **Gorunn** is a YAML file that defines the configuration for a project that is part of the stack. Example can be found in the [example stack](https://github.com/parapidcom/gorunn-project-manifests).\n#### Location\n```\n$HOME/gorunn/\n\u251c\u2500\u2500 myreact.yaml # Project manifest for the myreact app\n\u251c\u2500\u2500 mydjango.yaml # Project manifest for the mydjango app\n\u251c\u2500\u2500 env/\n\u251c\u2500\u2500\u2500 myreact.env # Environment files for the myreact app\n\u251c\u2500\u2500\u2500 mydjango.env # Environment files for the mydjango app\n```\n\n#### Structure\n\n- **git_repo**: git@github.com:parapidcom/gorunn-example-react (git repository url of the project)\n- **type**: node (type of the project, one of: node, php, python)\n- **version**: \"20\" (version of the platform being used, e.g. node version, php version, python version)\n- **endpoint**: myreact.local.gorunn.io (optional, if defined, the CLI will create a virtual host on the local proxy for it. The endpoint must be in the form of `%s.local.gorunn.io`)\n- **env_vars**: true (boolean, if true, the CLI will load it from manifests directory (if it does not exist, it will create a new file from a template))\n- **start_command**: npm run dev (command used to start the server)\n- **listen_port**: 3000 (port on which your local server will listen, allowing the proxy to forward to it as upstream)\n- **build_commands**: (list of commands necessary for project bootstrap. These are called with the `gorunn build --app app_name` command)\n\n\n## Project Manifests and Environment Files Location\nProject manifests locations defaults to `$HOME/gorunn/projects/` during `gorunn init`.\nCan be manually changed in the main configuration file.\n\n\n### Environment Variables\nEnvironment files are part of the project manifests directory structure. They are stored in `env/` subdir of the project manifests directory.\n\n\n#### Encrypt an environment file\n```bash\ngorunn projects env --encrypt --app myapp\n```\n\n#### Decrypt an environment file\n```bash\ngorunn projects env --decrypt --app myapp\n```\n\n### Project Management Commands\n\n#### Pull latest project manifests from remote repository\n```bash\ngorunn projects pull\n```\n\n#### Push project manifests and environment files changes to remote repository\n```bash\ngorunn projects publish\n```\n\n#### Show stack projects information\n```bash\ngorunn info\n```\n\n### Build Commands\n#### Build all projects defined in the project manifests directory\n```bash\ngorunn build --app all\n```\n\n#### Build specific project\n```bash\ngorunn build --app myapp\n```\n\n### Container Management\n\n#### Start containers\n```bash\ngorunn start [--app APP_NAME]\n```\n\n#### Stop containers\n```bash\ngorunn stop [--app APP_NAME]\n```\n\n#### Restart containers\n```bash\ngorunn restart [--app APP_NAME]\n```\n\n#### Stream logs\n```bash\ngorunn logs [--app APP_NAME] [--follow]\n```\n\n#### Access terminal\n```bash\ngorunn terminal --app APP_NAME\n```\n\n#### Aider AI assistant\nYou can use [Aider](https://aider.chat) to help you with your project if you have enabled it and provided your LLM API key.\n```bash\ngorunn aider --app APP_NAME --browser\n```\nThis will start Aider in browser mode and you can use it to help you code in browser on http://localhost:8501\n\n### Info\nPrint information about the stack.\n```bash\ngorunn info\n```\n\n### Version\nPrint currently installed **Gorunn** version.\n```bash\ngorunn version\n```\n\n#### Trust\nOn MacOS, you can add the **Gorunn**'s self signed certificate for `*.local.gorunn.io domain` to keychain.\nIt is done automatically during `gorunn init`.\n\n```bash\ngorunn trust\n```\n\n## Best Practices\n\n### Project Manifests\n- Keep manifests in version control\n- Use consistent naming conventions\n\n### Environment Variables\n - Always use encryption for sensitive data\n - Keep backup of encryption keys\n - Use separate env files per environment\n\n### Resource Management\n - Stop unused services to free resources\n - Regular cleanup using gorunn destroy\n - Monitor container logs for issues\n",
"bugtrack_url": null,
"license": null,
"summary": "CLI tool for managing local environments",
"version": "0.0.11",
"project_urls": {
"Homepage": "https://github.com/parapidcom/gorunn"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5cd0a33d28f46a015109b4cf893a4b307a5d298a8989fb2ead6262d5e6058179",
"md5": "80b719aaaa3355ab91bb31a55bbad1bc",
"sha256": "abc9d05e4a0a9248d71f1fb85616a37d71c7905339770a65a3bfafdf12648594"
},
"downloads": -1,
"filename": "gorunn-0.0.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "80b719aaaa3355ab91bb31a55bbad1bc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 62431,
"upload_time": "2024-11-14T18:28:05",
"upload_time_iso_8601": "2024-11-14T18:28:05.764563Z",
"url": "https://files.pythonhosted.org/packages/5c/d0/a33d28f46a015109b4cf893a4b307a5d298a8989fb2ead6262d5e6058179/gorunn-0.0.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4c56d55a2fbfe718954742a1a9a4d8541edda78df9e0b950dff21a305e52f69e",
"md5": "f4e057098cd74dc0380e8d8f165c4cf9",
"sha256": "4a71644fb34c8b724c1dbdf2bac12de4d3c1656ad54ff1578e63366a90516b27"
},
"downloads": -1,
"filename": "gorunn-0.0.11.tar.gz",
"has_sig": false,
"md5_digest": "f4e057098cd74dc0380e8d8f165c4cf9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 45702,
"upload_time": "2024-11-14T18:28:07",
"upload_time_iso_8601": "2024-11-14T18:28:07.514088Z",
"url": "https://files.pythonhosted.org/packages/4c/56/d55a2fbfe718954742a1a9a4d8541edda78df9e0b950dff21a305e52f69e/gorunn-0.0.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-14 18:28:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "parapidcom",
"github_project": "gorunn",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "click",
"specs": [
[
"==",
"8.1.7"
]
]
},
{
"name": "gitdb",
"specs": [
[
"==",
"4.0.11"
]
]
},
{
"name": "GitPython",
"specs": [
[
"==",
"3.1.43"
]
]
},
{
"name": "Jinja2",
"specs": [
[
"==",
"3.1.4"
]
]
},
{
"name": "MarkupSafe",
"specs": [
[
"==",
"2.1.5"
]
]
},
{
"name": "PyYAML",
"specs": [
[
"==",
"6.0.1"
]
]
},
{
"name": "smmap",
"specs": [
[
"==",
"5.0.1"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.2"
]
]
},
{
"name": "boto3",
"specs": [
[
"==",
"1.34.101"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"24.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
"==",
"1.0.1"
]
]
},
{
"name": "inquirer",
"specs": [
[
"==",
"3.4.0"
]
]
},
{
"name": "psutil",
"specs": [
[
"==",
"6.1.0"
]
]
},
{
"name": "cryptography",
"specs": [
[
"==",
"43.0.3"
]
]
}
],
"lcname": "gorunn"
}
JSON
