Akan 애플리케이션은 앱 코드, 생성 산출물, 서버 라우트, 페이지를 연결하는 Bun 기반 런타임 위에서 실행됩니다. 앱 엔트리 포인트(main.ts)는 런타임을 시작하고, 그 뒤의 서버 구성은 Akan이 담당합니다.

Akan App이 실행되면 Akan Server가 앱이 제공할 기능들을 준비합니다. 실제 런타임은 크게 네 가지 작업을 제공합니다.

AKAN_REPLICA는 역할별 서버 프로세스 개수를 정하며, 어디서나 기본값은 0,0,1입니다. all 서버 하나만 실행한다는 뜻입니다. 트래픽 replica가 하나면 분산할 대상이 없으므로, Akan App은 그 서버를 spawn해서 프록시하지 않고 자기 프로세스 안에서 직접 실행합니다. 컨테이너는 프로세스 하나만 갖고, 모든 요청이 프록시 홉을 건너뜁니다.

gateway가 다시 사용되는 경우는 다섯 가지입니다. replica가 둘 이상일 때, listen하지 않는 batch 전용 replica가 있을 때, AKAN_SOLO=false일 때, new AkanApp(...)에 replica를 넘겼을 때, 그리고 akan start일 때입니다. 이때 Akan App은 서버들을 spawn하고 준비된 federation/all 프로세스로 브라우저 요청을 로드밸런싱합니다.

루트 .env 파일은 앱이 실행될 때 사용할 조직, 도메인, 환경, 동작 모드, 로그 수준을 정합니다. 대부분의 프로젝트에서는 이 값을 자주 바꾸지 않지만, 값을 바꾸면 같은 앱을 로컬용, 디버그용, 개발 서버용, 운영에 가까운 형태로 실행할 수 있습니다.

이 중 네 개는 이 앱이 누구이며 어디서 도는지에 답하며, 앞의 두 개는 필수입니다:

실제로는 두 개를 같이 움직입니다. 기능을 만들 때는 ENV=local, OPERATION_MODE=local로 작업하고, 공용 데이터나 공용 서비스가 필요해지면 ENV를 debug나 develop으로 바꾸며, 배포할 때는 클러스터가 제공하는 operation mode에 맞춰 ENV=main으로 올립니다:

두 개는 서버에 닿는 쪽을 좁힙니다. 데스크톱 앱에 싣는 서버처럼 자기 컴퓨터만 부르는 서버용입니다:

전문 검색은 끄지 않는 한 켜져 있고, 두 변수 모두 프로세스별이 아니라 배포 전체의 결정이므로 한 배포의 모든 프로세스에 같은 값을 주세요.

레벨 사다리는 trace, verbose, debug, info, warn, error이고, 세 목적지가 이를 각각 따로 읽습니다. 컨테이너 stdout, 회전 로그 파일, 그리고 앱이 등록한 sink입니다. 나머지 변수들은 레코드에 얼마나 많은 구조가 함께 실려 가는지, 그리고 누가 더 많은 것을 요구할 수 있는지를 정합니다.

gateway(또는 단독 replica)가 akan logs --replay와 .trace를 위해 유지하는 링은 AKAN_LOG_BUFFER건 또는 AKAN_LOG_BUFFER_MB(기본 2,000건, 4MB) 중 먼저 차는 쪽까지 보관하고, 오래된 레코드부터 밀려납니다.

getEnv()는 .env 값을 앱이 실제로 사용할 런타임 정보로 정리해 주는 helper입니다. API URL이나 웹소켓 URL을 직접 조합하지 않고, 앱 코드에서는 getEnv()가 준비한 값을 읽어 사용할 수 있습니다.

Akan은 signal 파일에 선언된 HTTP query/mutation 표면을 OpenAPI 3.1 문서로 노출할 수 있습니다. Swagger, Redoc, 외부 클라이언트, SDK 생성 도구를 Akan이 이미 사용하는 API 형태에 연결할 때 유용합니다.

활성화한 뒤 앱 origin에서 /openapi.json을 요청하면 됩니다. 로컬 모드에서는 보통 localhost:8282/openapi.json에서 확인할 수 있습니다. 일반 API prefix는 /api를 유지하고, OpenAPI JSON은 프레임워크 메타데이터 route로 제공됩니다.

앱은 라이브러리가 선언한 모든 모듈을 마운트합니다. modules 옵션은 그 범위를 좁힙니다. 이 프로세스가 담당할 모듈을 지정하면 Akan은 그 모듈과 의존하는 모듈만 부팅하고 나머지는 컨테이너에 아예 올리지 않습니다. 빠진 모듈은 service, signal, route, 예약 작업이 모두 존재하지 않습니다. 하나의 코드베이스를 여러 개의 작은 프로세스로 나눠 실행하는 방법이며, 자기 도메인만 필요한 batch worker 같은 경우에 씁니다.

의존성은 프레임워크가 따라가므로 전체 그래프가 아니라 진입점만 적으면 됩니다. 지정한 모듈은 자신이 주입하는 service와 signal, 그리고 cascade로 삭제하는 model을 함께 끌어옵니다.

disableModules와 disableLibs는 반대편에서 좁힙니다. 지정한 대상과 그것을 참조하는 모듈만 빼고 전부 마운트합니다. disableLibs는 라이브러리 이름을 받아 그 라이브러리가 등록한 모듈 전부를 뜻합니다. 둘 다 modules를 쓰는 곳 어디서나 쓸 수 있고, 환경변수로는 AKAN_DISABLE_MODULES와 AKAN_DISABLE_LIBS입니다. modules와 제외 옵션에 같은 모듈을 적으면 빠집니다.

Akan 런타임은 앱이 살아있는지, 얼마나 바쁜지, 지금 무엇을 하고 있는지 확인할 수 있는 간단한 방법을 제공합니다. 로컬 개발에서는 페이지가 열리지 않거나 백그라운드 작업이 멈춘 것처럼 보일 때 유용합니다.