| Name | dotrun JSON |
| Version |
2.4.1
JSON |
| download |
| home_page | None |
| Summary | A tool for developing Node.js and Python projects |
| upload_time | 2024-08-21 14:36:48 |
| maintainer | None |
| docs_url | None |
| author | Canonical Web Team |
| requires_python | <4.0,>=3.10 |
| license | LGPL-3.0 |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<img src="https://assets.ubuntu.com/v1/14a3bac5-dotrun.svg?w=200" width="200" alt="dotrun" />
# A tool for developing Node.js and Python projects
`dotrun` makes use of a [Docker image](https://github.com/canonical/dotrun-image/) to provide a predictable sandbox for running Node and Python projects.
Features:
- Make use of standard `package.json` script entrypoints:
- `dotrun` runs `yarn run start` within the Docker container
- `dotrun foo` runs `yarn run foo` within the Docker container
- Detect changes in `package.json` and only run `yarn install` when needed
- Detect changes in `requirements.txt` and only run `pip3 install` when needed
- Run scripts using environment variables from `.env` and `.env.local` files
- Keep python dependencies in `.venv` in the project folder for easy access
## Usage
```bash
$ dotrun # Install dependencies and run the `start` script from package.json
$ dotrun serve # Run the python app only
$ dotrun clean # Delete `node_modules`, `.venv`, `.dotrun.json`, and run `yarn run clean`
$ dotrun install # Force install node and python dependencies
$ dotrun exec # Start a shell inside the dotrun environment
$ dotrun exec {command} # Run {command} inside the dotrun environment
$ dotrun {script-name} # Install dependencies and run `yarn run {script-name}`
$ dotrun -s {script} # Run {script} but skip installing dependencies
$ dotrun --env FOO=bar {script} # Run {script} with FOO environment variable
$ dotrun -m "/path/to/mount":"localname" # Mount additional directory and run `dotrun`
$ dotrun serve -m "/path/to/mount":"localname" # Mount additional directory and run `dotrun serve`
$ dotrun refresh image # Download the latest version of dotrun-image
$ dotrun --release {release-version} # Use a specific image tag for dotrun. Useful for switching versions
$ dotrun --image {image-name} # Use a specific image for dotrun. Useful for running dotrun off local images
```
- Note that the `--image` and `--release` arguments cannot be used together, as `--image` will take precedence over `--release`
## Installation
### Requirements
- Docker ([Get Docker](https://docs.docker.com/get-docker/)): on Linux, you can install the [Docker snap](https://snapcraft.io/docker) instead.
- Python 3.10 or later
- On MacOS: [Homebrew](https://docs.brew.sh/Installation) is required
- `curl` command-line tool (usually pre-installed on macOS and most Linux distributions)
### Linux and MacOS
#### Quick installation
To install dotrun simply run:
```bash
curl -sSL https://raw.githubusercontent.com/canonical/dotrun/main/scripts/install.sh | bash
```
### Verifying the Installation
After installation, you can verify that `dotrun` is installed correctly by running:
```bash
dotrun version
```
### Manual Installation
If you prefer to install manually or encounter any issues with the installation script, you can install `dotrun` using the following steps:
1. Install `pipx` if you haven't already:
* On macOS: `brew install pipx`
* On Linux: Follow the installation instructions for your distribution from the [pipx documentation](https://pypa.github.io/pipx/installation/)
2. Ensure `pipx` is in your PATH:
```bash
pipx ensurepath
```
1. Install `dotrun` using `pipx`:
```bash
pipx install dotrun
```
If you experience problems, please open a GitHub issue.
### macOS performance
For optimal performance on Docker we recommend enabling a new experimental file sharing implementation called virtiofs. Virtiofs is only available to users of the following macOS versions:
- macOS 12.2 and above (for Apple Silicon)
- macOS 12.3 and above (for Intel)
[How to enable virtiofs](https://www.docker.com/blog/speed-boost-achievement-unlocked-on-docker-desktop-4-6-for-mac/)
## Add dotrun on new projects
To fully support dotrun in a new project you should do the following:
- For Python projects, ensure [Talisker](https://pypi.org/project/talisker/) is at `0.16.0` or greater in `requirements.txt`
- Add `.dotrun.json` and `.venv` to `.gitignore`
- Create a `start` script in `package.json` to do everything needed to set up local development. E.g.:
`"start": "concurrently --raw 'yarn run watch' 'yarn run serve'"`
- The above command makes use of [concurrently](https://www.npmjs.com/package/concurrently) - you might want to consider this
- Older versions of Gunicorn [are incompatible with](https://forum.snapcraft.io/t/problems-packaging-app-that-uses-gunicorn/11749) strict confinement so we need Gunicorn >= 20
- The update [landed in Talisker](https://github.com/canonical-ols/talisker/pull/502) but at the time of writing hasn't made it into a new version
- If there's no new version of Talisker, simply add `gunicorn==20.0.4` to the bottom of `requirements.txt`
However, once you're ready to completely switch over to `dotrun`, simply go ahead and remove the `run` script.
### Automated tests of pull requests
[The "PR" action](.github/workflows/pr.yaml) builds the Python package and runs a project with dotrun. This will run against every pull request.
### Publish
All the changes made to the main branch will be automatically published as a new version on PyPI.
To publish a new version manually, run:
```
docker buildx create --name mybuilder
docker buildx use mybuilder
docker buildx build --push --platform linux/arm/v7,linux/arm64/v8,linux/amd64 --tag canonicalwebteam/dotrun-image:latest .
```
## Hacking
You can install the package locally using either pip or poetry.
### Using pip
```bash
pip3 install . requests==2.31.0
```
### Using Poetry
```bash
pip install poetry
poetry install --no-interaction
```
To run dotrun off alternative base images such as local images, you can use the `--image` flag.
```bash
dotrun --image "localimage" exec echo hello
```
To run dotrun off alternative releases, besides the `:latest` release, you can use the `--release` flag.
```bash
dotrun --release "latest" serve
```
Note that before changing the base image you should run
```bash
dotrun clean
```
to get rid of the old virtualenv.
Raw data
{
"_id": null,
"home_page": null,
"name": "dotrun",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Canonical Web Team",
"author_email": "webteam@canonical.com",
"download_url": "https://files.pythonhosted.org/packages/c7/72/cbec862584c9641123bb9089349fcb696321104ee71414f2e3ee18dcacf0/dotrun-2.4.1.tar.gz",
"platform": null,
"description": "<img src=\"https://assets.ubuntu.com/v1/14a3bac5-dotrun.svg?w=200\" width=\"200\" alt=\"dotrun\" />\n\n# A tool for developing Node.js and Python projects\n\n`dotrun` makes use of a [Docker image](https://github.com/canonical/dotrun-image/) to provide a predictable sandbox for running Node and Python projects.\n\nFeatures:\n\n- Make use of standard `package.json` script entrypoints:\n - `dotrun` runs `yarn run start` within the Docker container\n - `dotrun foo` runs `yarn run foo` within the Docker container\n- Detect changes in `package.json` and only run `yarn install` when needed\n- Detect changes in `requirements.txt` and only run `pip3 install` when needed\n- Run scripts using environment variables from `.env` and `.env.local` files\n- Keep python dependencies in `.venv` in the project folder for easy access\n\n## Usage\n\n```bash\n$ dotrun # Install dependencies and run the `start` script from package.json\n$ dotrun serve # Run the python app only\n$ dotrun clean # Delete `node_modules`, `.venv`, `.dotrun.json`, and run `yarn run clean`\n$ dotrun install # Force install node and python dependencies\n$ dotrun exec # Start a shell inside the dotrun environment\n$ dotrun exec {command} # Run {command} inside the dotrun environment\n$ dotrun {script-name} # Install dependencies and run `yarn run {script-name}`\n$ dotrun -s {script} # Run {script} but skip installing dependencies\n$ dotrun --env FOO=bar {script} # Run {script} with FOO environment variable\n$ dotrun -m \"/path/to/mount\":\"localname\" # Mount additional directory and run `dotrun`\n$ dotrun serve -m \"/path/to/mount\":\"localname\" # Mount additional directory and run `dotrun serve`\n$ dotrun refresh image # Download the latest version of dotrun-image\n$ dotrun --release {release-version} # Use a specific image tag for dotrun. Useful for switching versions\n$ dotrun --image {image-name} # Use a specific image for dotrun. Useful for running dotrun off local images\n```\n\n- Note that the `--image` and `--release` arguments cannot be used together, as `--image` will take precedence over `--release`\n\n## Installation\n\n### Requirements\n\n- Docker ([Get Docker](https://docs.docker.com/get-docker/)): on Linux, you can install the [Docker snap](https://snapcraft.io/docker) instead.\n- Python 3.10 or later\n- On MacOS: [Homebrew](https://docs.brew.sh/Installation) is required\n- `curl` command-line tool (usually pre-installed on macOS and most Linux distributions)\n\n### Linux and MacOS\n\n#### Quick installation\n\nTo install dotrun simply run:\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/canonical/dotrun/main/scripts/install.sh | bash\n```\n\n### Verifying the Installation\n\nAfter installation, you can verify that `dotrun` is installed correctly by running:\n\n```bash\ndotrun version\n```\n\n### Manual Installation\n\nIf you prefer to install manually or encounter any issues with the installation script, you can install `dotrun` using the following steps:\n\n1. Install `pipx` if you haven't already:\n\n * On macOS: `brew install pipx`\n * On Linux: Follow the installation instructions for your distribution from the [pipx documentation](https://pypa.github.io/pipx/installation/)\n2. Ensure `pipx` is in your PATH:\n\n```bash\npipx ensurepath\n```\n\n1. Install `dotrun` using `pipx`:\n\n```bash\npipx install dotrun\n```\n\nIf you experience problems, please open a GitHub issue.\n\n### macOS performance\n\nFor optimal performance on Docker we recommend enabling a new experimental file sharing implementation called virtiofs. Virtiofs is only available to users of the following macOS versions:\n\n- macOS 12.2 and above (for Apple Silicon)\n- macOS 12.3 and above (for Intel)\n\n[How to enable virtiofs](https://www.docker.com/blog/speed-boost-achievement-unlocked-on-docker-desktop-4-6-for-mac/)\n\n## Add dotrun on new projects\n\nTo fully support dotrun in a new project you should do the following:\n\n- For Python projects, ensure [Talisker](https://pypi.org/project/talisker/) is at `0.16.0` or greater in `requirements.txt`\n- Add `.dotrun.json` and `.venv` to `.gitignore`\n- Create a `start` script in `package.json` to do everything needed to set up local development. E.g.:\n `\"start\": \"concurrently --raw 'yarn run watch' 'yarn run serve'\"`\n - The above command makes use of [concurrently](https://www.npmjs.com/package/concurrently) - you might want to consider this\n- Older versions of Gunicorn [are incompatible with](https://forum.snapcraft.io/t/problems-packaging-app-that-uses-gunicorn/11749) strict confinement so we need Gunicorn >= 20\n - The update [landed in Talisker](https://github.com/canonical-ols/talisker/pull/502) but at the time of writing hasn't made it into a new version\n - If there's no new version of Talisker, simply add `gunicorn==20.0.4` to the bottom of `requirements.txt`\n\nHowever, once you're ready to completely switch over to `dotrun`, simply go ahead and remove the `run` script.\n\n### Automated tests of pull requests\n\n[The \"PR\" action](.github/workflows/pr.yaml) builds the Python package and runs a project with dotrun. This will run against every pull request.\n\n### Publish\n\nAll the changes made to the main branch will be automatically published as a new version on PyPI.\n\nTo publish a new version manually, run:\n\n```\ndocker buildx create --name mybuilder\ndocker buildx use mybuilder\ndocker buildx build --push --platform linux/arm/v7,linux/arm64/v8,linux/amd64 --tag canonicalwebteam/dotrun-image:latest .\n```\n\n## Hacking\n\nYou can install the package locally using either pip or poetry.\n\n### Using pip\n\n```bash\npip3 install . requests==2.31.0\n```\n\n### Using Poetry\n\n```bash\npip install poetry\npoetry install --no-interaction\n```\n\nTo run dotrun off alternative base images such as local images, you can use the `--image` flag.\n\n```bash\ndotrun --image \"localimage\" exec echo hello\n```\n\nTo run dotrun off alternative releases, besides the `:latest` release, you can use the `--release` flag.\n\n```bash\ndotrun --release \"latest\" serve\n```\n\nNote that before changing the base image you should run\n\n```bash\ndotrun clean\n```\n\nto get rid of the old virtualenv.\n\n",
"bugtrack_url": null,
"license": "LGPL-3.0",
"summary": "A tool for developing Node.js and Python projects",
"version": "2.4.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3983f041ee99d3affeac3116b6baa82ae686b9c5766623369d40948844473681",
"md5": "2a8a8395bfe1bebc2bb737d305c79100",
"sha256": "67156ab8bd3c2aa76841d0ea73f754d0dec56e1c0ef0289220191b38fe2fcf22"
},
"downloads": -1,
"filename": "dotrun-2.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2a8a8395bfe1bebc2bb737d305c79100",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 6765,
"upload_time": "2024-08-21T14:36:47",
"upload_time_iso_8601": "2024-08-21T14:36:47.130941Z",
"url": "https://files.pythonhosted.org/packages/39/83/f041ee99d3affeac3116b6baa82ae686b9c5766623369d40948844473681/dotrun-2.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c772cbec862584c9641123bb9089349fcb696321104ee71414f2e3ee18dcacf0",
"md5": "96b8afa6080e6f766a3692315a51973a",
"sha256": "c76b5429f56b2ddbd693d89775d0dfdf27b934a684a2f8c4f496064694c5c47f"
},
"downloads": -1,
"filename": "dotrun-2.4.1.tar.gz",
"has_sig": false,
"md5_digest": "96b8afa6080e6f766a3692315a51973a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 6139,
"upload_time": "2024-08-21T14:36:48",
"upload_time_iso_8601": "2024-08-21T14:36:48.003033Z",
"url": "https://files.pythonhosted.org/packages/c7/72/cbec862584c9641123bb9089349fcb696321104ee71414f2e3ee18dcacf0/dotrun-2.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-21 14:36:48",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "dotrun"
}
