diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2f6f6599b7..79e4ba027d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,7 @@ pip install invoke && invoke setup-dev --tests ```bash git clone https://github.com/inventree/InvenTree.git && cd InvenTree docker compose run inventree-dev-server invoke install -docker compose run inventree-dev-server invoke setup-test +docker compose run inventree-dev-server invoke setup-test --dev docker compose up -d ``` @@ -33,7 +33,7 @@ Run the following command to set up all toolsets for development. invoke setup-dev ``` -*We recommend you run this command before starting to contribute. This will install and set up `pre-commit` to run some checks before each commit and help reduce the style errors.* +*We recommend you run this command before starting to contribute. This will install and set up `pre-commit` to run some checks before each commit and help reduce errors.* ## Branches and Versioning diff --git a/docs/docs/start/docker_dev.md b/docs/docs/start/docker_dev.md index e74d3561e4..ef2710788f 100644 --- a/docs/docs/start/docker_dev.md +++ b/docs/docs/start/docker_dev.md @@ -35,7 +35,7 @@ To get "up and running" with a development environment, complete with a set of [ ```bash git clone https://github.com/inventree/InvenTree.git && cd InvenTree docker compose run inventree-dev-server invoke install -docker compose run inventree-dev-server invoke setup-test +docker compose run inventree-dev-server invoke setup-test --dev docker compose up -d ``` @@ -83,30 +83,33 @@ This command also performs the following steps: !!! info "Grab a coffee" This initial build process may take a few minutes! -### Create Admin Account - -If you are creating the initial database, you need to create an admin (superuser) account for the database. Run the command below, and follow the prompts: - -``` -docker compose run inventree-dev-server invoke superuser -``` - ### Import Demo Data To fill the database with a demo dataset, run the following command: -``` -docker compose run inventree-dev-server invoke setup-test +```bash +docker compose run inventree-dev-server invoke setup-test --dev ``` ### Start Docker Containers -Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the InvenTree containers: +Now that the database has been created, and migrations applied, we are ready to launch the InvenTree containers: -``` +```bash docker compose up -d ``` +### Create Admin Account + +If you are creating the initial database, you need to create an admin (superuser) account for the database. Run the command below, and follow the prompts: + +!!! info "Containers must be running" + For the `invoke superuser` command to execute properly, ensure you have run the `docker compose up -d` command. + +```bash +docker compose run inventree-dev-server invoke superuser +``` + This command launches the remaining containers: - `inventree-dev-server` - InvenTree web server @@ -115,6 +118,76 @@ This command launches the remaining containers: !!! success "Check Connection" Check that the server is running at [http://localhost:8000](http://localhost:8000). The server may take a few minutes to be ready. +## Running commands in the container + +Using `docker compose run [...]` commands creates a new container to run this specific command. +This will eventually clutter your docker with many dead containers that take up space on the system. + +You can access the running containers directly with the following: +```bash +docker exec -it inventree-dev-server /bin/bash +``` + +You then run the following to access the virtualenv: +```bash +source data/env/bin/activate +``` + +This sets up a bash terminal where you can run `invoke` commands directly. + +!!! warning "Tests" + Running `invoke test` in your currently active inventree-dev-server container may result in tests taking longer than usual. + +### Cleaning up old containers + +If you have Docker Desktop installed, you will be able to remove containers directly in the GUI. +Your active containers are grouped under "inventree" in Docker Desktop. +The main dev-server, dev-db, and dev-worker containers are all listed without the "inventree" prefix. +One time run containers, like those executed via `docker compose run [...]` are suffixed with `run-1a2b3c4d5e6f` where the hex string varies. + +To remove such containers, either click the garbage bin on the end of the line, or mark the containers, and click the delete button that shows up. +This is the recommended procedure for container cleanup. + +#### Advanced cleanup +!!! warning "Advanced users only" + This section requires good knowledge of Docker and how it operates. + Never perform these commands if you do not understand what they do + +If you're running a container with the general boilerplate commands used with invoke (invoke test, invoke update, etc) and no custom parameters or execution, you can add the `--rm` flag to `docker compose run`, and the container will delete itself when it goes down. +Do note that any data not stored in a volume, i.e. only in the container, will be lost when the container stops. + +To clean out old containers using the command line, follow this guide: + +Run the following command: +```bash +docker ps -a --filter status=exited +``` + +This gives you a list of all stopped containers. +Find the containers you wish to delete, copy the container IDs and add them to this command: + +```bash +docker rm [ID1] [ID2] [IDn] +``` +When executed, this removes all containers whose IDs were pasted. + +!!! warning "Execute at own risk" + The command below does not forgive errors. + Execute this only if you know what you're doing + +Running this command will remove **all** stopped one-time run InvenTree containers matching parameters: +```bash +docker container prune --filter label="com.docker.compose.oneoff=True" --filter label="com.docker.compose.service=inventree-dev-server" +``` + +The following output will appear: +``` +WARNING! This will remove all stopped containers. +Are you sure you want to continue? [y/N] y +Deleted Containers: +[IDs of any container that was deleted, one per line] +``` + ## Restarting Services Once initial setup is complete, stopping and restarting the services is much simpler: