{"id":18445461,"url":"https://github.com/nautobot/nautobot-docker-compose","last_synced_at":"2025-04-05T23:05:48.953Z","repository":{"id":40650650,"uuid":"352777815","full_name":"nautobot/nautobot-docker-compose","owner":"nautobot","description":"Docker Compose for Nautobot","archived":false,"fork":false,"pushed_at":"2025-03-10T15:28:17.000Z","size":380,"stargazers_count":56,"open_issues_count":14,"forks_count":52,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-29T22:08:04.406Z","etag":null,"topics":["docker","docker-compose","nautobot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nautobot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-29T20:36:05.000Z","updated_at":"2025-03-25T01:11:13.000Z","dependencies_parsed_at":"2024-01-19T15:43:07.016Z","dependency_job_id":"875c3abe-761a-4505-aeca-b5566280644e","html_url":"https://github.com/nautobot/nautobot-docker-compose","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nautobot%2Fnautobot-docker-compose","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nautobot%2Fnautobot-docker-compose/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nautobot%2Fnautobot-docker-compose/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nautobot%2Fnautobot-docker-compose/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nautobot","download_url":"https://codeload.github.com/nautobot/nautobot-docker-compose/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247411226,"owners_count":20934653,"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":["docker","docker-compose","nautobot"],"created_at":"2024-11-06T07:06:02.901Z","updated_at":"2025-04-05T23:05:48.928Z","avatar_url":"https://github.com/nautobot.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nautobot-docker-compose\n\nNetwork to Code has an existing published Nautobot Docker Image on Docker Hub. See [here](https://hub.docker.com/repository/docker/networktocode/nautobot). This project uses Docker Compose. The Docker compose file in this project pulls that Nautobot Docker image using the latest stable Nautobot release along with several other Docker images required for Nautobot to function. See the diagram below. This project is for those looking for a multi-container single-node install for Nautobot often coupled with backup \u0026 HA capabilities from their hypervisor manager.\n\n![Container Stack](docs/img/container_stack.png)\n\nBy default, this project deploys the Nautobot application, a single worker container, Redis containers, and PostgreSQL. It does not deploy NGINX, SSL, or any Nautobot plugins. However, the project is extensible to allow users to tailor it to their specific requirements. For example, if you need to deploy [SSL](docs/create_ssl_cert.md) or [plugins](docs/plugins.md), see the docs linked. The web server used on the application is [pyuwsgi](https://uwsgi-docs.readthedocs.io/en/latest/).\n\n## Docker Compose\n\nThis documentation is now written assuming the latest Docker Compose methodology of using the Docker Compose Plugin instead of the independent docker-compose executable. See the [Docker Compose Plugin installation notes](https://docs.docker.com/compose/install/)\n\n## Why Poetry?\n\nPoetry was chosen to replace both **requirements.txt** and **setup.py**. Poetry uses the `pyproject.toml` file to define package details, main package dependencies, development dependencies, and tool-related configurations. Poetry resolves dependencies and stores the hashes and metadata within the `poetry.lock` file (similar to performing a `pip freeze \u003e requirements.txt`). The `poetry.lock` is what is used to provide consistency for package versions across the project to make sure anyone who is developing on it is using the same Python dependency versions. Poetry also provides virtual environments by simply being in the same directory as the `pyproject.toml` and `poetry.lock` files and executing the `poetry shell` command.\n\n## Why Invoke?\n\nInvoke is a Python replacement for Make. Invoke looks for a `tasks.py` file that contains functions decorated by `@task` that provide the equivalents of **Make targets**.\n\nThe reason it was chosen over Makefile was due to our collective familiarity with Python and the ability to organize and re-use Invoke tasks across Cookiecutter templates.  It also makes managing your Nautobot project vastly simpler by issuing simple commands instead of long command strings that can be confusing.\n\n## How to use this repo\n\nThis repo is designed to provide a custom build of Nautobot to include a set of plugins which can then be used in a development environment or deployed in production.  Included in this repo is a skeleton Nautobot plugin which is designed only to provide a quick example of how a plugin could be developed.  Plugins should ultimately be built as packages, published to a PyPI style repository and added to the poetry `pyproject.toml` in this repo.  The plugin code should be hosted in their own repositories with their own CI pipelines and not included here.\n\n## Install Docker\n\nBefore beginning, install Docker and verify its operation by running `docker run hello-world`. If you encounter any issues connecting to the Docker service, check that your local user account is permitted to run Docker. **Note:** `docker` v1.10.0 or later is required.\n\n## Install Poetry\n\nIt is recommended to follow one of the [installation methods detailed in their documentation](https://python-poetry.org/docs/#installation).  It's advised to install poetry as a system-level dependency and not inside a virtual environment.  Once Poetry has been installed you can create the Poetry virtual environment with a few simple commands:\n\n1. `poetry shell`\n2. `poetry lock`\n3. `poetry install`\n\nThe last command, `poetry install`, will install all of the project dependencies for you to manage your Nautobot project.  This includes installing the `invoke` Python project.\n\n## Build and start Nautobot\n\nYou can build, deploy and populate Nautobot with the following steps\n\n1. `invoke build`\n2. `invoke start` or `invoke debug`\n\n\u003e The standard way of starting the containers is to use `invoke start`. If you wish to see the logs from the containers while running Nautobot use the `invoke debug` command. Be aware that exiting debug mode will stop all the containers.\n\nNautobot will be available on port 8080 locally http://localhost:8080\n\n## Cleanup Everything and start from scratch\n\n1. `invoke destroy`\n2. `invoke build`\n3. `invoke db-import`\n4. `invoke start`\n\n\u003e The `invoke db-import` command will only work if you have a previous backup of your database.\n\n## Export current database\n\nWhile the database is already running\n\n* `invoke db-export`\n\n### Docker Compose Files\n\nSeveral Docker Compose files are provided as [overrides](https://docs.docker.com/compose/extends/) to allow for various development configurations, these can be thought of as layers to Docker Compose, each Compose file is described below:\n\n* `docker-compose.postgres.yml` - Starts the prerequisite PostgreSQL service if using PostgreSQL as your database.\n* `docker-compose.mysql.yml` - Starts the prerequisite MySQL service if using MySQL as your database is desired.\n* `docker-compose.base.yml` - Defines the default Nautobot, Celery worker, Celery beats scheduler, and Redis services and how they should be run and built.\n* `docker-compose.ldap.yml` - Duplicate of `docker-compose.base.yml` file but points to LDAP-specific Dockerfile. This is done to make building an LDAP-supported installation easier.\n* `docker-compose.local.yml` - Defines how the Nautobot and Celery worker containers should run locally with port mappings and volume mounts. This is helpful as an example when you wish to create another instance, for example, a production instance, and you want to have the volume mounts and port mappings done differently.\n\n\u003e Only `docker-compose.postgres.yml` or `docker-compose.mysql.com` should be used as they are mutually exclusive and providing the same database backend service.\n\n### Environment Files\n\nEnvironment files (.env) are the standard way of providing configuration information or secrets in Docker containers. This project includes two example environment files that each serve a specific purpose:\n\n* `local.example.env` - The local environment file is intended to store all relevant configurations that are safe to be stored in git. This would typically be things like specifying the database user or whether debug is enabled or not. Do not store secrets, ie passwords or tokens, in this file!\n\n* `creds.example.env` - The creds environment file is intended to store all configuration information that you wish to keep out of git. The `creds.env` file is in `.gitignore` and thus will not be pushed to git by default. This is essential to keep passwords and tokens from being leaked accidentally.\n\nTo use the provided environment files it's suggested that you copy the file to the same name without the `example` keyword, ie:\n\n```bash\ncp environments/local.example.env environments/local.env\ncp environments/creds.example.env environments/creds.env\n```\n\n## CLI Helper Commands\n\nThe project comes with a CLI helper based on [invoke](http://www.pyinvoke.org/) to help manage the Nautobot environment. The commands are listed below in 2 categories `environment` and `utility`.\n\nEach command can be executed with a simple `invoke \u003ccommand\u003e`. Each command also has its own help `invoke \u003ccommand\u003e --help`.\n\n### Manage Nautobot environment\n\n```bash\n  build            Build all docker images.\n  debug            Start Nautobot and its dependencies in debug mode.\n  destroy          Destroy all containers and volumes.\n  start            Start Nautobot and its dependencies in detached mode.\n  stop             Stop Nautobot and its dependencies.\n  db-export        Export Database data to nautobot_backup.dump.\n  db-import        Import test data.\n```\n\n### Utility\n\n```bash\n  cli              Launch a bash shell inside the running Nautobot container.\n  migrate          Run database migrations in Django.\n  nbshell          Launch a nbshell session.\n```\n\n## Getting Started\n\n\u003e **NOTE**: Please be aware that you must be in the Poetry virtual environment before issuing any invoke commands. The steps to do this are detailed above.\n\n1. Have [Docker](https://docs.docker.com/get-docker/) installed on the host.\n2. Clone this repository to your Nautobot host into the current user directory.\n\n```bash\ngit clone https://github.com/nautobot/nautobot-docker-compose.git\n```\n\n3. Navigate to the new directory from the git clone.\n\n```bash\ncd nautobot-docker-compose\n```\n\n4. Copy the `local.env.example` file to `local.env` and `creds.example.env` file to `creds.env` in the environments folder.\n\n```bash\ncp environments/local.example.env environments/local.env\ncp environments/creds.example.env environments/creds.env\n```\n\n5. Update the `.env` files for your environment. **THESE SHOULD BE CHANGED** for proper security and the `creds.env` file should never be synchronized to git as it should contain all secrets for the environment!\n\n```bash\nvi environments/local.env\nvi environments/creds.env\n```\n\n6. Update the `local.env` and `creds.env` files to be only available for the current user.\n\n```bash\nchmod 0600 environments/local.env environments/creds.env\n```\n\n7. Copy the `invoke.example.yml` file to `invoke.yml`:\n\n```bash\ncp invoke.example.yml invoke.yml\n```\n\n8. Run `invoke build start` to build the containers and start the environment.\n\n```bash\ninvoke build start\n```\n\n### NOTE - MySQL\n\nIf you want to use MySQL for the database instead of PostgreSQL, perform the below step in place for step #7 above:\n\n```bash\ncp invoke.mysql.yml invoke.yml\n```\n\n### Getting Started - LDAP\n\nThe use of LDAP requires the installation of some additional libraries and some configuration in `nautobot_config.py`. See the [LDAP documentation](docs/ldap.md).\n\n### Getting Started - Plugins\n\nThe installation of plugins has a slightly more involved getting-started process. See the [Plugin documentation](docs/plugins.md).\n\n## Super User Account\n\n### Create Super User via Environment\n\nThe Docker container has a Docker entry point script that allows you to create a super user by the usage of Environment variables. This can be done by updating the `creds.env` file environment option of `NAUTOBOT_CREATE_SUPERUSER` to `True`. This will then use the information supplied to create the specified superuser.\n\n### Create Super User via Container\n\nAfter the containers have started:\n\n1. Verify the containers are running:\n\n```bash\ndocker container ls\n```\n\nExample Output:\n\n```bash\n❯ docker container ls\nCONTAINER ID   IMAGE                           COMMAND                  CREATED         STATUS                   PORTS                                                                                  NAMES\n143f10daa229   networktocode/nautobot:latest   \"nautobot-server rqw…\"   2 minutes ago   Up 2 minutes (healthy)                                                                                          nautobot-docker-compose_celery_worker_1\nbb29124d7acb   networktocode/nautobot:latest   \"/docker-entrypoint.…\"   2 minutes ago   Up 2 minutes (healthy)   0.0.0.0:8080-\u003e8080/tcp, :::8080-\u003e8080/tcp, 0.0.0.0:8443-\u003e8443/tcp, :::8443-\u003e8443/tcp   nautobot-docker-compose_nautobot_1\nad57ac1749b3   redis:alpine                    \"docker-entrypoint.s…\"   2 minutes ago   Up 2 minutes             6379/tcp                                                                               nautobot-docker-compose_redis_1\n5ab83264e6fe   postgres:10                     \"docker-entrypoint.s…\"   2 minutes ago   Up 2 minutes             5432/tcp                                                                               nautobot-docker-compose_postgres_1\n```\n\n2. Execute Create Super User Command and follow the prompts\n\n```bash\ninvoke createsuperuser\n```\n\nExample Prompts:\n\n```bash\nnautobot@bb29124d7acb:~$ invoke createsuperuser\nUsername: administrator\nEmail address:\nPassword:\nPassword (again):\nSuperuser created successfully.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnautobot%2Fnautobot-docker-compose","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnautobot%2Fnautobot-docker-compose","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnautobot%2Fnautobot-docker-compose/lists"}