> For the complete documentation index, see [llms.txt](https://docs.release.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.release.com/getting-started/prepare-to-use-release.md). # Prepare to use Release Take a look at [what you need to use Release](/readme.md#what-you-need-to-use-release) to be sure you meet the requirements. Release supports building and running complex applications. Release requires a `docker-compose.yml`, `package.json`, or `.release.yaml` file to be in the root of your application's Git repository. Release uses these files to generate the [Application Template](/reference-documentation/application-settings/application-template.md) that is used as a blueprint to build your environments. If your application has nested directories where your `docker-compose.yaml` or `package.json` files reside, you can add a `.release.yaml` file to the root of your repository to tell Release where these files are located. See [The `.release.yaml` file](/reference-documentation/release.yaml.md) reference guide for more information. We recommend using a [monorepo](https://en.wikipedia.org/wiki/Monorepo) and a directory-per-service at the project root when your application requires two or more services. Here is an example directory structure for three services that require docker builds: ``` ├── README.md ├── docker-compose.yml ├── result │ └── Dockerfile ├── vote │ └── Dockerfile └── worker └── Dockerfile ``` If you're not using a monorepo, you can create an application for each repository and connect them using environment variables in each of those applications. See [Microservices architecture](/guides-and-examples/advanced-guides/microservices-architecture.md) for more information. ## Testing Docker Compose for Release The best way to test if your application will run in Release is to get **Docker Compose** to run your application locally. See [Overview of Docker Compose](https://docs.docker.com/compose/) for more details. **Release allows you to quickly spin up containerized services without the traditional wait times involved with cloud-native services.** When running an application locally or in a Release **ephemeral environment**, we recommend that you isolate your application's external dependencies. Consider using *off-the-shelf* Docker images to represent the cloud-native services that your application depends on, such as Postgres, Redis, etc. Visit [Docker Hub](https://hub.docker.com) to find many off-the-shelf Docker images. You can use environment variables to connect **ephemeral environments** to AWS-native services such as RDS, however, we recommend using these off-the-shelf Docker images to speed up deployment and simplify set up. This is an example of a `docker-compose.yml` file that builds three Docker images and leverages two off-the-shelf containers for **Redis** and **Postgres**: ```yaml version: "3" services: vote: build: ./vote command: python app.py volumes: - ./vote:/app ports: - "5000:80" depends_on: - "worker" result: build: ./result command: nodemon server.js volumes: - ./result:/app ports: - "5001:80" depends_on: - "worker" worker: build: context: ./worker depends_on: - "redis" - "db" redis: image: redis:alpine container_name: redis db: image: postgres:9.4 container_name: db volumes: - "db-data:/var/lib/postgresql/data" volumes: db-data: ``` Release detects many popular services such as **Redis**, **MySQL**, **Postgres**, **RabbitMQ**, and **many more**, and will handle opening standard ports for these services. Here's an example of adding Redis, RabbitMQ, and Memcached with minimal configuration in Docker Compose: ```yaml version: "3" services: redis: image: "redis:5-alpine" rabbitmq: image: "rabbitmq:3.7-alpine" memcached: image: "memcached:1.5-alpine" ``` ### Building your application Release supports most options from [`docker-compose build`](https://docs.docker.com/compose/compose-file/#build). Release looks for all services with a `build` stanza, and executes a **docker build** for each service found. #### Specify the current working directory: ```yaml version: "3" services: app: build: . ``` #### Specify a different directory to build: ```yaml version: "3" services: vote: build: ./vote ``` #### Specify the Dockerfile and pass in [build arguments](/reference-documentation/account-settings/build-settings/build-args.md): ```yaml version: "3" services: mysql: build: context: . dockerfile: Dockerfile-mysql args: S3_BUCKET: "data.example.com" MYSQL_VERSION: "5.7" ``` ### Release ports and DNS hostnames Release uses the [`docker-compose` ports](https://docs.docker.com/compose/compose-file/#ports) (`HOST:CONTAINER`) definition to determine when a service should be exposed to the internet. When Release encounters a service with a `HOST:CONTAINER` definition, it creates a **NodePort**, **load balancer rule**, and **DNS hostname** entry for the service. ```yaml version: "3" services: frontend: build: context: . dockerfile: Dockerfile-frontend ports: - "8080:8080" command: ["npm", "run", "dev-server-docker"] ``` In this example, Release creates a hostname for the frontend service that exposes port 8080. **Internal services**, like your **data stores**, **caches**, and **background workers**, should not be exposed to the internet, and should only be available internally to other services defined in your `docker-compose`. ```yaml version: "3" services: db: image: postgres:9.4 ports: - "5432" ``` This example shows **Postgres** opening a container port on **5432** that another service can consume. ### Environment variables Most applications use **environment variables** to define how services talk to each other and/or change the behavior of an application in a given environment. **Release uses the environment variables provided in your `docker-compose` as a starting point.** All of the environment variables for each service defined in your `docker-compose` are loaded into Release when you initially create an application. Release supports all of the standard `docker-compose` mechanisms for defining environment variables. You can use [`env` file](https://docs.docker.com/compose/env-file/) to specify an external `env` file: ```yaml version: "3" services: api: build: context: ./api dockerfile: Dockerfile.django ports: - "8000:8000" env_file: .env ``` You can also set environment variables directly in your `docker-compose` file: ```yaml version: "3" services: nginx: build: . ports: - "5000:5000" environment: - AWS_REGION=us-west-2 - AWS_SECRET_ACCESS_KEY=XXX - RESOLVER=8.8.8.8 ``` If you have dynamic or secret environment variables, you can read more about [environment-specific environment variables](https://github.com/releasehub-com/docs/blob/main/reference-guide/environment-settings/environment-specific-environment-variables/README.md) in our reference guide. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.release.com/getting-started/prepare-to-use-release.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.