튜토리얼의 문제점

2022년 3월 8일 Burke Holland, @burkeholland

훌륭한 튜토리얼을 작성하는 것은 쉽지 않습니다. 저는 그것을 잘 알아야 합니다. 저는 많은 튜토리얼을 작성했으며, 모든 튜토리얼이 대성공을 거두지는 못했습니다.

결론적으로 훌륭한 튜토리얼을 만드는 것은 무엇을 쓰는지에 관한 것이 아니라, 개발자가 모든 단어를 읽지 않고도 성공할 수 있는지에 관한 것입니다. 이 글에서는 개발 컨테이너가 사용자가 겪을 수 있는 오류를 어떻게 줄일 수 있는지, 그리고 Laravel PHP 프로젝트가 자체 튜토리얼에서 이를 얼마나 우아하게 구현하여 큰 효과를 거두는지 살펴보겠습니다.

아무도 읽지 않는다

Visual Studio Code에서 Dev Containers 사용 방법에 대한 저희 자체 튜토리얼은 항상 완료율이 낮았습니다. 약 4~6% 정도였습니다.

dev containers learn module screenshot

사람들이 어디서 포기하는지 알아내기 위해 사용자 연구를 수행하고 사람들이 튜토리얼을 완료하려고 시도하는 것을 지켜보았습니다. 그것은... 고통스러웠습니다.

사람들이 튜토리얼을 완료하지 못한 이유가 분명했습니다. 아무도 그것을 읽지 않았습니다. 사람들은 지침을 건너뛰고 바로 실행 단계로 넘어갔습니다. 결국, 지침을 읽었다면 하지 않았을 오류를 범했기 때문에 막혔습니다.

펜실베이니아 주립 대학의 John M. Carroll 교수는 그의 기념비적인 저서 The Nurnberg Funnel - Designing Minimalist Instruction for Practical Computer Skill에서 이 점을 논합니다. 그는 이렇게 씁니다. "[학습자는] 지침을 많이 활용하기에는 너무 바빠서 학습합니다. 이것이 의미 형성의 역설입니다."

저도 이것에 공감하며, 아마 여러분도 그럴 것입니다. 저는 튜토리얼을 진행할 때, 코드를 보면서 배우려고 눈이 코드 블록을 훑고 있습니다. 저는 말 그대로 학습하느라 지침을 읽을 시간이 없습니다.

사람들은 당신의 튜토리얼을 읽지 않을 것입니다. 또는 적어도 당신이 원하는 만큼은 읽지 않을 것입니다. 당신이 할 수 있는 최선의 방법은 학습 과정에서 독자가 오류를 범할 수 있는 곳을 가능한 한 많이 제거하는 것입니다. 그렇게 하는 한 가지 방법은 사전 구성된 컨테이너 환경을 사용하여 환경 설정 단계를 완전히 제거하는 것입니다.

컨테이너화된 개발 환경

튜토리얼의 상당 부분은 일반적으로 필수 구성 요소 및 환경 설정 목록에 할애됩니다. 저는 Ruby on Rails를 배우면서 Windows에 Ruby를 올바르게 설치하려고 대부분의 시간을 보냈던 것을 분명히 기억합니다. "gem"이 무엇인지, 그리고 왜 모두 누락되었는지 궁금해하면서 말입니다.

컨테이너화된 개발 환경의 아이디어는 Docker 컨테이너 내에서 개발한다는 것입니다. 이를 통해 완전히 이식 가능하고 완벽하게 구성된 개발 환경을 자유롭게 구축하거나 해체할 수 있습니다. 그런 다음 해당 환경을 구성 파일 세트로 다른 사람에게 제공할 수 있습니다.

하지만 컨테이너 안에서 어떻게 개발하나요? 컨테이너에는 VS Code를 실행할 수 있는 UI가 있는 것이 아닙니다.

VS Code용 Dev Containers 확장 프로그램이 바로 그것을 합니다. 이 확장 프로그램에는 Docker 컨테이너를 개발 환경으로 구성하는 메커니즘과 VS Code에서 해당 환경에 연결할 수 있는 기능이 모두 포함되어 있습니다. 이는 컨테이너 내부에 작은 서버 구성 요소를 설치하여 로컬 VS Code와 통신하는 방식으로 작동합니다. 그런 다음 로컬 환경에 있는 것처럼 개발하지만, VS Code는 로컬 환경 대신 컨테이너 환경에 연결됩니다.

The Dev Containers extension screenshot from extension gallery

컨테이너화된 개발 환경을 만들기 위해서는 일반적으로 Docker에 대해 어느 정도 알아야 합니다. 많은 사람들이 알고 있지만, 모르는 사람들도 많습니다(보이지는 않겠지만 제 손이 들려 있습니다). 그래서 이 확장 프로그램은 컨테이너 설정 과정을 최대한 추상화하려고 합니다. 저는 새로운 Python 컨테이너를 설정했습니다. 마법사가 기본 이미지와 Python 버전을 선택하도록 안내합니다. 그런 다음 선택 목록을 통해 이미지에 추가 소프트웨어를 추가할 기회를 제공합니다. 이 경우 Azure CLI, Dotnet CLI 및 PowerShell을 추가합니다…

Adding a dev container configuration to a Python project

이 프로세스는 필요한 Dockerfile을 포함하여 .devcontainer 폴더를 이 프로젝트에 추가합니다. 또한 Dev 컨테이너의 측면(예: 설치해야 하는 확장 프로그램, 컨테이너 빌드 후 실행해야 하는 설정 명령 등)을 정의하는 표준인 devcontainer.json 파일도 추가합니다. 환경과 설정을 완전히 제어할 수 있으므로 종속성 설치, 라이브러리 버전 등 거의 모든 것을 자동화할 수 있습니다.

이러한 방식으로 추가 설정 단계나 Ruby gem에 대한 실존적 위기를 유발할 필요 없이 완전하고 즉시 사용 가능한 환경을 말 그대로 다른 사람에게 전달하는 것이 가능합니다.

일부 개발자들은 이미 Dev 컨테이너 기반 접근 방식을 사용하여 사용자들을 매우 복잡한 환경에서도 빠르게 시작할 수 있도록 하고 있습니다. PHP용 Laravel 프레임워크가 좋은 예입니다.

Laravel 솔루션

Laravel은 PHP용 오픈 소스 MVC 프레임워크입니다. 객체 관계형 매퍼(ORM), 직접 데이터베이스 액세스, 패키지 시스템 등도 포함한다는 점에서 포괄적입니다. Laravel은 많은 것을 할 수 있습니다. 그리고 그것을 경험하려면, 시작할 때 최소한 데이터베이스가 필요합니다. 일반적으로 사용자가 PHP뿐만 아니라 데이터베이스(일반적으로 MySQL)도 설치해야 합니다. 사용자가 단순히 프레임워크를 시험해 보는 단계에서는 상당한 요구 사항입니다.

Laravel은 컨테이너화된 개발 환경과 Sail이라는 도구로 이를 해결합니다. Laravel, MySQL 서버 및 Redis 캐시로 처음부터 시작하려면 단 한 번의 명령만 실행하면 됩니다...

    curl -s "https://laravel.build/example-app?with=mysql,redis" | bash

이렇게 하면 docker-compose 파일이 있는 새 프로젝트가 생성됩니다. 이 파일은 애플리케이션 컨테이너, MySQL 컨테이너 및 Redis 컨테이너의 세 가지 컨테이너를 설정합니다. 컨테이너나 세 가지 서비스에 대해 아무것도 알 필요가 없습니다. Sail은 이 모든 것을 추상화합니다. 그런 다음 Sail 명령을 실행하여 환경을 시작합니다...

    ./vendor/bin/sail up

샘플 애플리케이션이 실행됩니다. PHP 설치 없음. Laravel 없음. 종속성 해결 단계 없음. 즉각적인 성공.

An example Laravel application running in the browser on localhost

프로젝트에 MySQL 서버와 Redis 캐시가 있다고 지정했으므로 프로젝트가 시작될 때 실제로는 세 개의 컨테이너가 생성됩니다. VS Code용 Docker 확장 프로그램을 사용하여 이를 확인할 수 있습니다.

The Docker extension in VS Code

이 컨테이너들은 서로 네트워킹되어 앱 컨테이너에서 MySQL 또는 Redis 캐시 컨테이너를 호출할 수 있습니다.

sail-8.1/app container에 대화형 터미널을 연결하면 /var/www/html 폴더에서 프로젝트를 볼 수 있습니다. Docker는 머신에서 프로젝트를 컨테이너로 "마운트"하므로 개발 중에 수행하는 모든 변경 사항은 새로 고침할 때 애플리케이션에 반영됩니다.

The file structure of the Laravel project in a container

Dev Containers 추가

Dev Containers 확장 프로그램에 대한 지원도 추가되었습니다. 이 프로젝트에 적절한 Dev Container 구성을 추가하려면 동일한 프로젝트를 스캐폴딩하고 &devcontainer 플래그를 추가할 수 있습니다.

    curl -s "https://laravel.build/example-app?with=mysql,redis&devcontainer" | bash

기존 Sail/Laravel 프로젝트에 Dev Container를 추가하려면 php artisan sail:install --devcontainer를 실행하면 됩니다.

이렇게 하면 동일한 프로젝트 구성이 생성되지만 .devcontainer 폴더가 포함됩니다. VS Code는 자동으로 해당 폴더를 감지하고 프로젝트를 컨테이너에서 다시 열도록 프롬프트하므로 필요한 sail up 단계를 건너뛸 수 있습니다.

A notification in VS Code saying "Reopen in container"

VS Code는 컨테이너에 연결되므로 로컬 환경이 아닌 컨테이너 환경 내부에서 개발하게 됩니다. VS Code의 왼쪽 하단에 있는 Remote Indicator가 이를 알려줍니다...

The remote indicator in VS Code showing connection to a container

컨테이너 외부에서 개발하는 것과 내부에서 개발하는 것에는 몇 가지 뚜렷한 이점이 있습니다.

개발 컨텍스트가 앱 컨텍스트를 반영합니다.

컨테이너에 연결되면 개발 중인 컨텍스트는 애플리케이션이 실행되는 컨텍스트와 동일합니다. 따라서 터미널은 컨테이너의 터미널이 됩니다...

The VS Code terminal connected to the running container instance

Dev Containers 확장 프로그램은 전달되는 포트와 같이 더 완전한 정보를 제공하여 애플리케이션이 어디에서 실행되는지 잊어버리는 경우에도 도움이 됩니다.

The port forwarding view in VS Code showing port 80 forwarded

Laravel 애플리케이션이 자동으로 시작되고 애플리케이션 로그는 컨테이너 로그로 파이프됩니다. 애플리케이션에서 무슨 일이 일어나고 있는지 확인하고 싶을 것이므로 Dev Containers 확장 프로그램은 VS Code에서 새로운 보기를 제공하여 실행 중인 모든 컨테이너를 보고 컨테이너 로그를 스트리밍하는 데 연결할 수 있습니다.

The Laravel application container logs in VS Code

개발 환경 설정 자동화

최고의 개발자 경험에는 편집기 사용자 지정이 포함됩니다. 여기에는 편집기 자체 설정과 기본 경험에 추가해야 하는 확장 프로그램 또는 기타 지원이 포함됩니다.

VS Code 및 Laravel의 경우, devcontainer.json에 확장 프로그램이 제안되지만 자동으로 설치되지 않도록 주석 처리되어 있습니다. 이렇게 하면 사용자가 편집기를 올바르게 구성하는 방법을 찾아야 하는 대신 미리 식별된 확장 프로그램 세트에서 선택할 수 있습니다.

    ...
    "extensions": [
        // "mikestead.dotenv",
        // "amiralizadeh9480.laravel-extra-intellisense",
        // "ryannaddy.laravel-artisan",
        // "onecentlin.laravel5-snippets",
        // "onecentlin.laravel-blade"
    ],

더 적게 읽고, 더 많이 실행

사람들은 읽지 않습니다. 그리고 그것은 괜찮아야 합니다. Laravel의 튜토리얼이 다른 튜토리얼보다 반드시 짧은 것은 아니지만, 중요한 것은 코드로 바로 가서 명령을 실행하면 작동한다는 것입니다. Dev 컨테이너가 그것을 가능하게 합니다. 이제 저희 자체 튜토리얼인 Use a Docker container as a development environment with Visual Studio Code에 대한 Dev Container를 만드는 방법을 알아낼 수만 있다면 좋을 것입니다...

행복한 코딩 되세요!

Burke Holland (@burkeholland)