https://github.com/evidence-dev/docker-devenv
This repo builds a Docker image whose container instances can be used as a development environment for Evidence projects via a mounted directory
https://github.com/evidence-dev/docker-devenv
Last synced: 3 months ago
JSON representation
This repo builds a Docker image whose container instances can be used as a development environment for Evidence projects via a mounted directory
- Host: GitHub
- URL: https://github.com/evidence-dev/docker-devenv
- Owner: evidence-dev
- License: mit
- Created: 2022-05-03T20:14:02.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-12-13T17:36:22.000Z (over 1 year ago)
- Last Synced: 2025-08-23T06:03:49.820Z (9 months ago)
- Language: Shell
- Size: 43 KB
- Stars: 16
- Watchers: 2
- Forks: 6
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Docker Development Environment
The Evidence Docker Development Environment (devenv) image is available on [Docker Hub](https://hub.docker.com/repositories/evidencedev).
The `devenv` image can be used as a development environment for Evidence projects by running it as a container with a mounted directory. Utilizing this container allows developers to work on Evidence sites without the need to install any additional toolchains other than `Docker`. For instance, there is no necessity to install `npm` or `node`.
This repository contains the Dockerfiles, the publishing actions, and usage documentation pertaining to [Evidence `devenv` images](https://hub.docker.com/repositories/evidencedev).
## Using the Evidence Docker Development Environment
### Pre-requisites
Ensure the Docker tool chain is installed via [Docker Desktop](https://www.docker.com/products/docker-desktop/) (recommended) OR using [binaries](https://docs.docker.com/engine/install/binaries/).
### Starting the Docker Evidence Development Environment
#### Option 1: Create a **new Evidence project** from scratch using the Evidence project template:
```
cd
docker run -v=$(pwd):/evidence-workspace -p=3000:3000 -it --rm evidencedev/devenv:latest --init
```
* Make sure your project is in the allowed directory (https://docs.docker.com/desktop/settings-and-maintenance/settings/#virtual-file-shares)
* In this case, `` should be an empty directory.
* You should see the template site up when you point your browser to `localhost:3000`.
* You should see new files, copied from the Evidence project template, in ``.
* Any subsequent edits made in `` should be reflected on the browser.
* If you are using Windows without PowerShell, you will need to replace `$(pwd)` with the full path to your Evidence project root directory or `%cd%`
#### Option 2: Work with an **existing Evidence** project
```
cd
docker run -v=$(pwd):/evidence-workspace -p=3000:3000 -it --rm evidencedev/devenv:latest
```
* Make sure your project is in the allowed directory (https://docs.docker.com/desktop/settings-and-maintenance/settings/#virtual-file-shares)
* In this case, `` should contain an Evidence project.
* You should see your site up when you point your browser to `localhost:3000`.
* Any edits made in `` should be reflected on the browser.
* If you are using Windows without PowerShell, you will need to replace `$(pwd)` with the full path to your Evidence project root directory or `%cd%`
##### Note for M1/M2 Mac Users using DuckDB
* If you are using an ARM M1/M2 Mac (Late 2021 Macs and later), you will need to use the `--platform linux/amd64` flag to run the Evidence devenv container with either of the options above. For instance:
```
cd
docker run -v=$(pwd):/evidence-workspace -p=3000:3000 -it --rm --platform linux/amd64 evidencedev/devenv:latest
```
* Startup can be quite slow due to emulation. You may want to consider an alternative approach such as using Codespaces mentioned below.
### Alternative Start Options
#### Using a Script to Start the Docker Development Evironment
If you'd rather not type out the docker commands, you have the option of starting the devenv with a [script](./starting-with-script.md) detailed [here](./running-with-script.md).
#### Running a Smaller Image
If you are not using DuckDB, and you have limited storage on your disk, you can use a smaller `devenv` image by replacing the `evidencedev/devenv:latest` image with `evidencedev/devenv-lite:latest` in the above commands.
### Connecting to a Database from the Development Container
* You can setup your DB connection as [documented](https://docs.evidence.dev/core-concepts/data-sources/). However there are few caveats to note when using the Evidence development environment container.
* If your database is hosted on your `host` machine, you'll have to ensure that the Database host is set to `host.docker.internal` either via the settings or your database config file (instead of `localhost`, `0.0.0.0`, etc). For instance:
```
{
"host": "host.docker.internal",
"database": "yourDBname",
"port": 5432,
"user": "yourUsername"
}
```
* If your database is hosted externally (e.g on the cloud), you'll have to ensure your docker container has permissions to access the outside world.
### Stopping the Running devenv container
* Option 1: `docker ps` to list all running containers, and copy the container ID of the running Evidence development environment container, and then run `docker stop `.
* Option 2: Use `Ctrl+C` to stop the running container on terminal.
## Alternative to Using the Evidence Devenv
Github Codespaces are another way to setup an Evidence dev environment without installing `npm`, `node` etc. See [Evidence installation docs](https://docs.evidence.dev/getting-started/install-evidence) for more information.
## Development notes
This section only applies if you are contributing to this repo.
### Testing the image locally
```
docker build -t .
cd
docker run -v=$(pwd):/evidence-workspace -p=3000:3000 -it --rm
```
### Manually publishing the latest image to Docker Hub (Evidence team only)
Currently the image is hosted on Docker Hub and are re-built on pushes to main. To build and publish a new version manually, follow these steps
1. Login to Docker Hub => `docker login`
2. Build and push the image => `docker buildx build --platform linux/amd64,linux/arm64 -t evidencedev/devenv:latest . --push`