Anatomy of an Environment

File Structure

The default directory of an environment is /var/environment. You are automatically placed there when connecting via SSH using your IDE or terminal, and when opening the Visual Studio Code web interface.

Inside the /var/environment directory, you will find the different repositories that make up your project:

└── /var/environment/
   ├── my-repository/
   └── my-other-repository/

When an environment is started, Protocode generates a .protocode-runtime folder that is stored at the root of each repository within the project. This folder contains all the files required for the environment's operation:

└── /var/environment/
   ├── my-dépôt/
   │   └── .protocode-runtime/
   │      └── .env 
   │      └── docker-compose.yml
   │      └── lifecycle/
   │         └── prePull.sh
   │         └── postPull.sh
   │         └── preUp.sh
   │         └── postUp.sh
   │         └── preFreeze.sh
   │         └── preDown.sh
   │      └── version
   │ ... Rest of my files

These files have the following roles:

• .env : This file contains all the environment variables entered in the repository's configuration. These variables will be injected into each docker-compose command.

• docker-compose.yml : This is the configuration file generated by Protocode for Docker Compose. It is the file that will be used when calling docker-compose from the root of a repository (even if another docker-compose.yml file exists at the same level). For example, you can stop all containers with a command like:

cd my-repository # Move from the default directory to the repository
docker-compose down

You can then modify some values in the startup file (.protocode-runtime/docker-compose.yml) and restart the containers by running:

cd /var/environment/my-repository
docker-compose up -d

• lifecycle : This folder contains all the initialization scripts created at the environment's start and will be executed during the different [life cycle stages]().

• version : This file contains version information necessary for operation.

Preinstalled Tools

An environment is an instance of Debian 11, which includes several tools necessary for its operation, including:

• For virtualization: Docker, Docker Compose
• For source versioning: Git, Git LFS
• For terminal use: Bash, Zsh
• For file editing: Vim, Nano
• For file retrieval: Curl, Wget

Docker Containers

Your environment is like a remote workstation running containers with Docker. When you connect, you are placed in the default directory and outside of your containers. If you open a terminal and enter the following command to list your containers:

docker ps

You will see a return like:

CONTAINER ID   IMAGE              COMMAND                  CREATED       STATUS       PORTS                 NAMES
3a70f7c8c765   node:16            "docker-entrypoint.s…"   10 days ago   Up 10 days   80/tcp                protocode-web_app
6703eddacc5d   protocode-api_app  "docker-php-entrypoi…"   3 weeks ago   Up 3 weeks   80/tcp, 9000/tcp      protocode-api-app
82c3d52d0e50   mysql:8.0          "docker-entrypoint.s…"   3 weeks ago   Up 3 weeks   3306/tcp, 33060/tcp   protocode-api-database

Since you are in the default directory and not inside one of your repositories, any docker-compose command will result in an error because Docker Compose will not find a configuration file in the default directory. You need to first navigate to the repository and then run a docker-compose command:

cd my-repository
docker-compose exec app bash # In this example, enter the terminal of a container

In short, it is no different than using Docker locally.

Git

Git is installed at the environment level and has been configured to communicate with the various repositories that make up your project, allowing you to fetch sources and push changes.

By default, each repository is positioned on the branch selected as "Default" in its configuration (see Add a Git repository). It is up to the developer, as in a local setup, to create their own working branch on each repository and to stay up to date (using git pull / git rebase depending on your habits).