Exploring the Docksal Command-line Utility (with examples)

Introduction

Docksal is a powerful tool for developing and managing local development environments. The Docksal command-line utility, also known as fin, provides a set of handy commands to interact with Docksal projects and containers. In this article, we will explore different use cases of the fin command, along with code examples, motivations, explanations, and sample outputs.

Use Case 1: Starting a Project

The fin project start command allows you to start a project in the current directory. This command initializes the development environment and launches all the necessary containers.

Code:

fin project start

Motivation: You can use this command when you need to start your Docksal project after cloning it from a repository or when initializing a new project.

Explanation: The fin project start command initializes the project, provisions the required services, and starts the containers defined in your .docksal/docksal.yml file.

Example Output:

Starting project...
Creating network "project_default" with the default driver
Creating volume "project_dbsync" with default driver
(...)

Use Case 2: Stopping a Project

The fin project stop command allows you to stop a project in the current directory. This command terminates all running containers associated with the project.

Code:

fin project stop

Motivation: You may need to stop a project to conserve system resources or when you no longer need to run the development environment.

Explanation: The fin project stop command stops all containers running within the current project directory.

Example Output:

Stopping project...
Stopping project_db_1   ... done
Stopping project_web_1  ... done
(...)

Use Case 3: Opening a Shell in a Container

The fin bash container_name command allows you to open a shell session inside a specific container.

Code:

fin bash container_name

Motivation: You might need to access the terminal of a specific container to carry out debugging, troubleshooting, or running specific commands within its environment.

Explanation: The fin bash command allows you to open a new shell session inside the specified container. Replace container_name with the name of the container (e.g., web, db, proxy) you wish to access.

Example Output:

Opening shell session in container...
root@5c1f83507058:/var/www/default# 

Use Case 4: Displaying Container Logs

The fin logs container_name command allows you to display logs of a specific container.

Code:

fin logs container_name

Motivation: When troubleshooting issues within a Docker container, it is often helpful to review its logs to identify potential errors or unexpected behavior.

Explanation: The fin logs command displays the logs generated by the specified container. Replace container_name with the name of the container (e.g., web, db, proxy) you want to view logs for.

Example Output:

Displaying logs for container...
[INFO] Xdebug is disabled in PHP configuration.
(...)

Use Case 5: Following Container Logs

The fin logs -f container_name command displays the logs of a specific container and continuously follows the log output.

Code:

fin logs -f container_name

Motivation: Following container logs in real-time can be useful when monitoring application events, debugging, or investigating continuous integration/continuous delivery (CI/CD) pipelines.

Explanation: The fin logs -f command follows the logs generated by the specified container, displaying the real-time output as new log entries are added.

Example Output:

Following logs for container...
[DEBUG] Incoming request GET /about-us
[DEBUG] Rendering view: about-us.twig
(...)

Conclusion

The Docksal command-line utility (fin) provides a convenient way to manage your Docksal projects and interact with specific containers. We explored different use cases of the fin command, including starting and stopping projects, opening shells inside containers, displaying and following container logs. Armed with these examples, you can confidently utilize Docksal and the fin command to streamline your local development workflow.