Akan 런타임

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

apps/myapp/main.ts

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

Internal API (Queue, Timer, etc.): 브라우저 요청 없이 내부에서 실행되는 큐, 타이머 같은 작업입니다.
API (HTTP, WebSocket): 데이터 요청과 실시간 업데이트를 처리하는 HTTP, 웹소켓 통신 경로입니다.
SSR Pages (Web): 서버가 렌더링해서 브라우저로 보내는 웹 페이지입니다.
CSR Page (Android, iOS): Android, iOS 같은 모바일 대상에서 사용하는 클라이언트 렌더링 페이지입니다.

Runtime overview

하나의 Akan App은 하나 이상의 Akan Server 프로세스를 실행할 수 있습니다. AKAN_REPLICA는 역할별 서버 프로세스 개수를 제어하므로, 같은 앱 안에서 웹 트래픽과 백그라운드 작업을 나누어 확장할 수 있습니다. 브라우저 요청은 Akan App이 준비된 federation/all 서버로 로드밸런싱합니다.

federation: 페이지, API 호출, 웹소켓 연결 같은 브라우저 요청을 처리합니다.
batch: 큐, 타이머, 예약 작업 같은 백그라운드 작업을 실행합니다.
all: 하나의 서버 프로세스에서 federation과 batch 역할을 함께 실행합니다. 로컬 개발에서 사용하는 단순한 기본 형태입니다.

Replica and server modes

단일 Akan App은 clustering 기능을 기본으로 지원합니다. 여러 server replica를 실행하고 Akan App이 트래픽을 분산할 수 있으므로, nginx, docker compose, pm2 같은 별도 로컬 load-balancing 도구를 직접 구성하지 않아도 됩니다.

루트 환경변수

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

.env

AKAN_PUBLIC_ 접두사가 붙은 환경변수는 공개 값입니다. 브라우저 코드에서도 읽을 수 있으므로 비밀키, 개인 토큰, 인증 정보는 절대 넣지 마세요.

AKAN_PUBLIC_REPO_NAME

프로젝트 소유자

조직 또는 저장소 네임스페이스입니다. 보통 프로젝트 값으로 고정합니다.

ex) akansoft

AKAN_PUBLIC_SERVE_DOMAIN

공개 도메인

앱이 링크, 콜백, 도메인 기반 라우팅을 만들 때 사용하는 도메인입니다.

ex) "akanjs.com"

AKAN_PUBLIC_ENV

데이터 환경

사용할 데이터 기준에 따라 local, debug, develop, main 중에서 선택합니다.

ex) local | debug | develop | main

AKAN_PUBLIC_OPERATION_MODE

연결 대상

클라이언트가 로컬 런타임, 엣지 경로, 클라우드 서비스 중 어디에 연결될지 정합니다.

ex) local | edge | cloud

AKAN_PUBLIC_LOG_LEVEL

로그 상세도

터미널에 어느 정도 자세한 런타임 로그를 볼지 정합니다.

ex) trace | debug | info | warn | error

AKAN_LOG_FILE_LEVEL

파일 로그 상세도

파일에 저장할 structured Logger 출력 범위를 정합니다. 기본값은 trace이며 터미널 로그 레벨과 별도로 동작합니다.

ex) trace | debug | info | warn | error

AKAN_LOG_TO_FILE

파일 로그

AkanApp은 기본적으로 gateway와 child process 로그를 runtime/logs에 저장합니다. 파일 로그를 끄려면 0으로 설정합니다.

ex) 0 | 1

AKAN_LOG_DIR

로그 디렉터리

파일 로그가 사용하는 기본 runtime/logs 디렉터리를 다른 경로로 바꿉니다.

ex) /var/log/akan

AKAN_LOG_MAX_SIZE_MB

로그 회전 크기

프로세스별 로그 파일이 이 크기에 도달하면 다음 sequence 파일을 만듭니다.

ex) 50

AKAN_LOG_MAX_FILES

로그 보관 개수

gateway 또는 child-0 같은 process key별로 보관할 회전 로그 파일 개수입니다.

ex) 100

AKAN_PUBLIC_ENV 모드

local

내 컴퓨터와 로컬 테스트 데이터

debug

재현을 위한 공용 테스트 데이터

develop

팀 통합 상태 확인

main

운영에 가까운 동작 확인

AKAN_PUBLIC_OPERATION_MODE 모드

local

클라이언트가 로컬 런타임에 연결

cloud

클라이언트가 클라우드 서비스에 연결

edge

클라이언트가 엣지 경로 사용

자주 쓰는 설정 예시

로컬에서 기능 개발

공용 테스트 데이터로 재현

클라우드 서버에 프로덕션 배포

엣지 서버에 프로덕션 배포

일반적으로 기능을 만들 때는 ENV=local, OPERATION_MODE=local로 작업합니다. 데이터베이스 마이그레이션이나 서비스를 확인해야 할 때는 ENV를 debug 또는 develop으로 바꿔 테스트합니다.

getEnv()

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

Using getEnv()

로컬 모드

OPERATION_MODE가 local이면 getEnv()는 브라우저와 API 클라이언트가 내 로컬 Akan 런타임을 바라보도록 합니다. 보통 localhost:8282를 사용합니다.

local

클라우드 / 엣지 모드

OPERATION_MODE가 cloud 또는 edge이면 getEnv()는 앱 이름, 환경, 서비스 도메인을 조합해 서비스 URL을 만듭니다.

cloud / edge

앱 코드에서 런타임 주소나 환경 식별 정보가 필요할 때는 getEnv()를 사용하세요. URL 결정이 한곳에 모이기 때문에 local, cloud, edge 모드를 더 쉽게 전환할 수 있습니다.

상태 확인, 메트릭, 로그

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

상태 확인

게이트웨이와 서버 프로세스가 실행 중이고 준비되었는지 확인할 때 사용합니다.

health

메트릭

활성 요청, 웹소켓 연결, room, 프로세스 지표 같은 런타임 수치를 확인할 때 사용합니다.

metrics

로그

터미널에 어느 정도 자세한 로그를 볼지는 AKAN_PUBLIC_LOG_LEVEL로 조절합니다. AkanApp은 기본적으로 gateway와 child process 출력을 runtime/logs에 저장하며, structured Logger 출력은 AKAN_LOG_FILE_LEVEL 기준으로 저장하고 날짜와 크기 기준으로 파일을 회전합니다.

logs

파일명에는 app name, environment, operation mode, 로컬 날짜, process key, sequence가 포함됩니다. child server의 직접 console.log 호출은 stdout/stderr pipe를 통해 저장되지만, gateway process의 직접 console.log 호출은 Logger sink 캡처 대상이 아닙니다.

Runtime checks

앱이 응답하지 않으면 먼저 health를 확인하세요. 응답은 하지만 바빠 보이면 metrics를 확인합니다. 더 자세한 터미널 정보가 필요할 때는 LOG_LEVEL을 올리거나 AKAN_MEMORY_LOG를 켭니다.