이번 글에서는 Oracle Always Free VM에서 실행 중인 Docker 기반 FastAPI를 Nginx reverse proxy와 Cloudflare DNS/Proxy를 통해 도메인으로 연결한 과정을 정리한다.

애플리케이션 실행 환경은 Cloudflare Worker가 아니다. FastAPI는 표준 Docker 컨테이너로 실행하고, Cloudflare는 DNS, Proxy, D1, R2 역할을 담당한다.

1. 최종 아키텍처

사용자 브라우저
-> example.com
    -> Cloudflare DNS / Proxy
    -> Oracle VM 공인 IP
    -> Nginx :443
    -> Nginx reverse proxy
    -> 127.0.0.1:8000
    -> Docker Compose
    -> Uvicorn
    -> FastAPI
    -> Cloudflare D1 / R2

각 계층의 책임은 다음처럼 나눴다.

• FastAPI: 애플리케이션과 API 제공
• Docker: 실행 환경 패키징
• Uvicorn: ASGI 애플리케이션 서버
• Nginx: HTTPS 종료와 reverse proxy
• Oracle VM: 애플리케이션 실행 서버
• Cloudflare: DNS, Proxy, D1, R2
• Gabia: 도메인 등록 기관

FastAPI는 특정 클라우드의 실행 런타임에 종속되지 않는다. Oracle VM 대신 다른 Linux VM이나 컨테이너 호스팅 서비스를 사용하더라도 Docker 실행 계층은 재사용할 수 있다.

2. Oracle VM에 Docker 애플리케이션 실행

Ubuntu VM에 Docker, Compose plugin, Git을 설치했다.

sudo apt update
sudo apt install -y docker.io docker-compose-v2 git
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"

그룹 권한을 적용하기 위해 SSH 세션을 종료한 뒤 다시 접속했다.

exit

소스는 배포 브랜치에서 내려받는다.

mkdir -p ~/apps
cd ~/apps
git clone --branch feature/FastAPI-migration <repository-url>
cd <repository-directory>

운영 환경변수는 저장소에 커밋하지 않고 VM에서 직접 작성한다.

cp .env.example .env
chmod 600 .env
nano .env

주요 설정은 다음과 같다.

SECRET_KEY=<long-random-secret>
DATABASE=/app/instance/app.db
UPLOAD_FOLDER=/app/uploads
MAX_CONTENT_LENGTH=20971520
DISPLAY_TIMEZONE=Asia/Seoul

REPOSITORY_BACKEND=d1
STORAGE_BACKEND=r2

CLOUDFLARE_ACCOUNT_ID=<cloudflare-account-id>
D1_DATABASE_ID=<d1-database-id>
CLOUDFLARE_API_TOKEN=<d1-runtime-api-token>

R2_BUCKET_NAME=<r2-bucket-name>
R2_ACCOUNT_ID=<cloudflare-account-id>
R2_ACCESS_KEY_ID=<r2-access-key-id>
R2_SECRET_ACCESS_KEY=<r2-secret-access-key>
R2_PUBLIC_BASE_URL=<r2-public-base-url>

D1 API Token과 R2 S3 Access Key는 서로 다른 인증 수단이다. CLOUDFLARE_API_TOKEN은 D1 REST API 호출에 사용하고, R2는 R2_ACCESS_KEY_ID와 R2_SECRET_ACCESS_KEY를 사용한다.

3. Docker Compose로 FastAPI 실행

Oracle VM용 Compose 설정은 FastAPI 포트를 외부에 직접 노출하지 않도록 구성했다.

services:
  fastapi:
    build:
      context: ../..
      dockerfile: Dockerfile
    container_name: personal-service-fastapi
    restart: unless-stopped
    env_file:
      - ../../.env
    ports:
      - "127.0.0.1:8000:8000"
    volumes:
      - fastapi-instance:/app/instance

volumes:
  fastapi-instance:

컨테이너는 다음처럼 실행한다.

cp deployment/oracle/docker-compose.yml.example deployment/oracle/docker-compose.yml
docker compose -f deployment/oracle/docker-compose.yml up -d --build

FastAPI는 127.0.0.1:8000에서만 수신한다. 외부 요청은 Nginx만 받도록 하여 애플리케이션 포트를 인터넷에 직접 공개하지 않는다.

4. Nginx reverse proxy 구성

Docker 컨테이너가 실행된 다음 VM에 Nginx를 설치한다.

sudo apt update
sudo apt install -y nginx
sudo systemctl enable --now nginx

/etc/nginx/sites-available/example.com에 다음 설정을 작성한다.

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name example.com www.example.com;

    ssl_certificate /etc/nginx/ssl/example.com.pem;
    ssl_certificate_key /etc/nginx/ssl/example.com.key;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

사이트를 활성화한다.

sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/example.com
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

Nginx는 외부의 80, 443 요청을 받아 내부 FastAPI의 8000 포트로 전달한다. FastAPI 포트를 127.0.0.1에만 바인딩했기 때문에 외부 사용자는 Nginx를 거치지 않고 컨테이너에 직접 접근할 수 없다.

5. Oracle 네트워크 포트 설정

Oracle Cloud Console의 VCN 보안 목록에 다음 Ingress Rule을 추가했다.

Source CIDR: 0.0.0.0/0
Protocol: TCP
Destination Port: 80

Source CIDR: 0.0.0.0/0
Protocol: TCP
Destination Port: 443

SSH 접속을 위한 22번 포트도 필요하다. 운영 환경에서는 0.0.0.0/0 대신 본인의 고정 IP 대역으로 제한하는 것이 안전하다.

Oracle 보안 목록을 통과해도 Ubuntu 내부 방화벽 규칙에서 차단될 수 있다. 서버에서는 iptables의 INPUT 규칙에 80, 443을 허용하고 영구 저장했다.

sudo iptables -I INPUT 5 -p tcp --dport 80 -m conntrack --ctstate NEW -j ACCEPT
sudo iptables -I INPUT 5 -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
sudo apt install -y iptables-persistent
sudo netfilter-persistent save

외부 연결은 다음 세 계층을 모두 통과해야 한다.

Oracle VCN Security List -> Ubuntu iptables -> Nginx

6. Gabia 도메인을 Cloudflare로 연결

구매한 도메인은 Gabia에 그대로 두고 DNS 운영만 Cloudflare로 이전했다.

Cloudflare에서 도메인을 추가하면 사용할 네임서버를 할당한다. 이번에 할당된 네임서버는 다음과 같았다.

<cloudflare-nameserver-1>
<cloudflare-nameserver-2>

Gabia 도메인 관리 화면의 네임서버 설정에서 기존 Gabia 네임서버를 삭제하고 Cloudflare 네임서버를 등록한다.

1차: <cloudflare-nameserver-1>
2차: <cloudflare-nameserver-2>

DNSSEC를 사용 중이었다면 네임서버를 바꾸기 전에 비활성화해야 한다. DNSSEC 상태가 남아 있으면 네임서버 변경 후 DNS 응답 검증이 실패할 수 있다.

네임서버 전파 여부는 다음 명령으로 확인할 수 있다.

nslookup -type=ns example.com 1.1.1.1

7. Cloudflare DNS 레코드 설정

Cloudflare DNS에 Oracle VM의 Reserved Public IP를 등록한다.

Type: A
Name: @
IPv4 address: <oracle-reserved-public-ip>
Proxy status: Proxied

www도 사용할 경우 CNAME을 추가한다.

Type: CNAME
Name: www
Target: example.com
Proxy status: Proxied

Oracle VM의 공인 IP는 Ephemeral IP가 아닌 Reserved IP를 사용하는 편이 안전하다. Reserved IP는 해제하기 전까지 유지할 수 있어 VM 교체 시에도 같은 IP를 다시 연결할 수 있다.

8. Cloudflare Origin Certificate

Cloudflare Proxy가 HTTPS로 원본 서버에 연결하려면 Oracle VM의 Nginx에도 인증서가 필요하다.

Cloudflare Dashboard에서 다음 메뉴로 이동한다.

SSL/TLS
  -> Origin Server
  -> Create Certificate

호스트 이름에는 다음을 포함한다.

example.com
*.example.com

인증서 발급 후 화면에 표시되는 두 값을 구분해야 한다.

Origin Certificate -> 공개 인증서 파일(.pem)
Private Key        -> 개인 키 파일(.key)

두 값을 각각 VM에 저장한다.

sudo mkdir -p /etc/nginx/ssl
sudo nano /etc/nginx/ssl/example.com.pem
sudo nano /etc/nginx/ssl/example.com.key
sudo chmod 600 /etc/nginx/ssl/example.com.key

Private Key는 저장소, 메신저, 블로그, 화면 캡처에 포함하면 안 된다.

9. Cloudflare SSL 모드

원본 Nginx에도 Cloudflare Origin Certificate를 설치했으므로 Cloudflare의 SSL/TLS 암호화 모드는 Full (strict)를 사용한다.

Full
  Cloudflare에서 원본까지 HTTPS로 연결하지만 인증서 검증은 엄격하지 않음

Full (strict)
  Cloudflare에서 원본까지 HTTPS로 연결하고 인증서 유효성 및 호스트 이름을 검증

원본 인증서가 정상적으로 설치된 운영 환경에서는 Full (strict)가 적합하다. Cloudflare와 원본 사이에서도 인증서를 검증하므로 Full보다 안전하다.

10. 배포 구조 확인

각 구간을 분리하면 연결 문제를 빠르게 찾을 수 있다.

1. 컨테이너 -> 127.0.0.1:8000
2. Nginx -> 127.0.0.1:8000
3. VM 공인 IP -> Nginx :80/:443
4. 도메인 DNS -> Cloudflare
5. Cloudflare Proxy -> Oracle Origin

서버 내부에서 Nginx가 FastAPI로 전달하는지 확인할 때는 Host 헤더를 지정한다.

curl -H "Host: example.com" http://127.0.0.1/health

도메인과 HTTPS 연결 후에는 다음처럼 접근한다.

curl.exe -i https://example.com/health

Cloudflare Proxy를 사용하는 경우 외부 응답에는 Cloudflare 관련 헤더가 표시되고, 응답 본문은 FastAPI가 반환한 내용이어야 한다.

11. 배포 결과와 한계

최종적으로 애플리케이션 실행과 저장소를 다음처럼 분리했다.

실행 계층: Oracle Always Free VM + Docker + Nginx
데이터 계층: Cloudflare D1
파일 계층: Cloudflare R2
네트워크 계층: Cloudflare DNS / Proxy

FastAPI는 Worker 전용 코드 없이 일반 ASGI 애플리케이션으로 실행된다. 따라서 로컬에서는 Uvicorn으로 실행하고, 서버에서는 Docker Compose로 실행하며, 필요하면 다른 클라우드의 VM이나 컨테이너 플랫폼으로 옮길 수 있다.

Always Free VM은 리전의 호스트 용량과 계정 상태에 영향을 받고, E2.1.Micro처럼 자원이 작은 인스턴스는 이미지 빌드와 메모리 사용량에 주의해야 한다. 실행 서버를 교체할 수 있도록 데이터와 파일을 D1/R2에 분리한 이유도 여기에 있다.

마무리

이번 배포의 핵심은 FastAPI를 Cloudflare Worker로 변환하지 않고, 일반 Docker 서비스로 실행하면서 Cloudflare의 관리형 서비스를 연결한 것이다.

FastAPI는 어디서나 실행 가능하게
Cloudflare는 DNS, Proxy, D1, R2로 사용
Nginx는 외부 요청과 내부 애플리케이션 사이의 경계로 사용

이 구조를 기반으로 이후에는 자동 배포, 운영 로그, 백업, 접근 제어와 모니터링을 추가할 수 있다.

부록. PythonAnywhere와 응답 속도 비교

배포 후 기존 PythonAnywhere 주소와 새 도메인의 응답 속도를 간단히 비교했다.

두 서비스에서 공통으로 응답하는 루트 경로를 대상으로 PowerShell에서 각각 3회 요청했고, DNS 조회나 페이지 렌더링 시간은 제외하고 HTTP 요청의 전체 응답 시간을 측정했다.

측정 경로: /
측정 횟수: 각 3회

PythonAnywhere 평균: 약 0.893초
Oracle VM + Cloudflare 평균: 약 0.491초

측정 환경에서는 새 배포 구조가 기존 PythonAnywhere보다 약 0.4초 빠르게 응답했으며, 전체 응답 시간이 약 45% 감소했다.

다만 이 결과는 단일 환경에서 짧게 측정한 참고값이다. 실제 속도는 네트워크 상태, Cloudflare Proxy 경로, 서버 부하, 응답 데이터 크기와 캐시 여부에 따라 달라질 수 있다. 또한 /health 경로는 PythonAnywhere 서비스에 존재하지 않아 404가 반환되었으므로 속도 비교에서는 사용하지 않았다.

처음에는 Cloudflare에서 FastAPI 애플리케이션까지 실행하는 구조를 검토했다. 하지만 Cloudflare Container는 Workers Paid 플랜이 필요했고, 애플리케이션 실행 환경을 Cloudflare에 종속시키지 않으려는 기존 방향과도 완전히 맞지는 않았다.

그래서 실행 서버는 Oracle Cloud의 Always Free VM으로 분리하고, 데이터와 파일 저장소는 기존처럼 Cloudflare D1/R2를 사용하는 구조를 선택했다.

1. 최종적으로 선택한 구조

사용자 브라우저
    -> Cloudflare DNS / Proxy
    -> Oracle Always Free VM
    -> Docker Compose
    -> Uvicorn
    -> FastAPI
    -> Cloudflare D1 / R2

각 서비스의 역할은 다음처럼 분리했다.

• Oracle VM: FastAPI 애플리케이션 실행
• Docker: 실행 환경 패키징
• Uvicorn: ASGI 서버
• Cloudflare D1: 운영 데이터 저장
• Cloudflare R2: 에셋과 문서 이미지 저장
• Cloudflare DNS/Proxy: 도메인, HTTPS, 외부 접근 제어

FastAPI는 표준 Docker 이미지로 실행하므로 다른 VM이나 다른 클라우드로 옮겨도 같은 방식으로 배포할 수 있다.

2. Cloudflare Container 대신 Oracle VM을 선택한 이유

Cloudflare Container는 무료 Workers 플랜에서 사용할 수 없고 Workers Paid 플랜이 필요하다.

무료 티어를 우선하는 상황에서 Oracle Always Free VM은 다음 장점이 있었다.

• FastAPI를 일반 Docker 애플리케이션으로 실행할 수 있음
• Cloudflare Worker 전용 런타임에 종속되지 않음
• 기존 D1/R2 연결을 유지할 수 있음
• 나중에 다른 VM이나 클라우드로 옮기기 쉬움

최종 구조는 Oracle을 애플리케이션 실행 서버로만 사용하고, D1/R2는 저장소 서비스로 유지하는 방식이다.

3. VCN과 Subnet 구성

VM 생성 화면에서 네트워크를 함께 만들 수도 있지만, Public Subnet이 정확히 선택되지 않으면 공인 IPv4를 할당할 수 없다. 그래서 VCN을 먼저 만들었다.

Oracle Console에서 다음 메뉴로 이동했다.

Networking
  -> Virtual cloud networks
  -> Start VCN Wizard
  -> Create VCN with Internet Connectivity

사용한 CIDR 구성은 다음과 같다.

VCN CIDR Block:             10.0.0.0/16
Public Subnet CIDR Block:   10.0.1.0/24
Private Subnet CIDR Block:  10.0.2.0/24

처음에는 Private Subnet 기본값이 Public Subnet과 같은 10.0.1.0/24로 들어가 있어서 CIDR이 겹쳤다. 같은 VCN 안의 Subnet은 주소 범위가 겹치면 안 되므로 Private Subnet을 10.0.2.0/24로 변경했다.

최종 네트워크는 다음과 같다.

fastapi-vcn
  -> Public Subnet   10.0.1.0/24
  -> Private Subnet  10.0.2.0/24

VM은 외부 SSH와 웹 요청을 받아야 하므로 Public Subnet에 배치한다.

4. A1 인스턴스 생성 시도와 용량 부족

처음에는 Oracle Always Free의 Ampere A1 인스턴스를 사용하려고 했다.

Shape: VM.Standard.A1.Flex
OCPU: 1
Memory: 6GB
Image: Ubuntu

그러나 다음 오류가 발생했다.

Out of capacity for shape VM.Standard.A1.Flex in availability domain AD-1.

이 오류는 설정 오류나 결제 오류가 아니라 해당 Availability Domain의 호스트 용량 부족이다. 현재 계정의 Home Region에서는 AD-1만 표시되어 다른 Availability Domain으로 옮길 수도 없었다.

A1 용량이 언제 확보될지 알 수 없는 상태에서 기다리는 것보다 우선 서비스를 실행하기 위해 VM.Standard.E2.1.Micro를 생성했다.

Shape: VM.Standard.E2.1.Micro
Memory: 1GB

E2.1.Micro는 테스트와 소규모 실행용으로는 사용할 수 있지만 메모리와 CPU가 작다. 또한 E2.1.Micro는 나중에 A1.Flex로 단순 변경할 수 없다.

A1 용량이 확보되면 새 VM을 만들고 같은 Docker 이미지와 환경변수로 재배포해야 한다. D1/R2를 외부 저장소로 사용하고 있기 때문에 실행 VM을 교체해도 핵심 데이터는 유지된다.

5. Public IP와 네트워크 확인

VM 생성 시 다음을 선택했다.

Virtual cloud network: fastapi-vcn
Subnet: Public Subnet
Public IPv4 address: Automatically assign

VM 상세의 Detail 탭에는 IP 정보가 요약되어 보이지 않을 수 있다. 실제 IP는 다음 위치에서 확인할 수 있었다.

VM 상세 화면
  -> Networking 탭
  -> Primary VNIC
  -> Private IPs

공인 IP가 할당된 상태라면 Primary VNIC에 Private IP도 존재한다.

외부 접속에 필요한 보안 규칙도 추가했다.

TCP 22  SSH
TCP 80  HTTP
TCP 443 HTTPS

6. Windows에서 SSH 연결

Oracle에서 SSH Private Key를 다운로드한 뒤 Windows에서 접속하려고 하자 다음 오류가 발생했다.

WARNING: UNPROTECTED PRIVATE KEY FILE!
Permissions for 'ssh-key.key' are too open.

Windows 파일 권한에 Authenticated Users가 포함되어 있어서 OpenSSH가 개인 키를 거부한 것이다.

PowerShell에서 상속 권한을 제거하고 현재 사용자에게만 읽기 권한을 부여했다.

$key = "G:\Oracle_key\ssh-key.key"
icacls $key /inheritance:r
icacls $key /remove "Authenticated Users" "Users" "Everyone"
icacls $key /grant:r "$($env:USERNAME):(R)"

그 후 다음 명령으로 접속할 수 있었다.

ssh -i "G:\Oracle_key\ssh-key.key" ubuntu@<oracle-public-ip>

Windows에서는 별도의 SSH 프로그램보다 Windows Terminal의 기본 OpenSSH 클라이언트를 사용하는 편이 간단했다. 이후 원격 파일 편집이 필요하면 VS Code Remote-SSH를 사용할 수 있다.

7. E2.1.Micro에 Swap 추가

E2.1.Micro는 메모리가 1GB이므로 Docker 설치나 이미지 빌드 중 메모리 부족이 발생할 수 있다. 그래서 2GB Swap을 추가했다.

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h

Swap은 RAM을 대체하지 않지만 설치 과정에서 프로세스가 즉시 종료되는 상황을 완화할 수 있다.

8. Docker와 FastAPI 소스 설치

Ubuntu VM에 Docker, Compose plugin, Git을 설치했다.

sudo apt update
sudo apt install -y docker.io docker-compose-v2 git
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"

Docker 그룹 권한을 적용하기 위해 SSH 세션을 종료한 뒤 다시 접속했다.

exit

이후 마이그레이션 브랜치의 소스를 내려받았다.

mkdir -p ~/apps
cd ~/apps
git clone --branch feature/FastAPI-migration https://github.com/jhpark-jarvis/maple-life-docs.git
cd maple-life-docs

9. 운영 환경변수 설정

운영 환경변수는 저장소에 커밋하지 않고 서버에서 직접 작성한다.

cp .env.example .env
chmod 600 .env
nano .env

주요 설정은 다음과 같다.

SECRET_KEY=<long-random-secret>
DATABASE=/app/instance/app.db
UPLOAD_FOLDER=/app/uploads
MAX_CONTENT_LENGTH=20971520
DISPLAY_TIMEZONE=Asia/Seoul

REPOSITORY_BACKEND=d1
STORAGE_BACKEND=r2

CLOUDFLARE_ACCOUNT_ID=<cloudflare-account-id>
D1_DATABASE_ID=<d1-database-id>
CLOUDFLARE_API_TOKEN=<d1-runtime-api-token>

R2_BUCKET_NAME=<r2-bucket-name>
R2_ACCOUNT_ID=<cloudflare-account-id>
R2_ACCESS_KEY_ID=<r2-access-key-id>
R2_SECRET_ACCESS_KEY=<r2-secret-access-key>
R2_PUBLIC_BASE_URL=<r2-public-base-url>

FLASK_ENV=production
FLASK_DEBUG=0

처음 .env.example에는 다음과 같은 placeholder가 있었다.

DATABASE={}
UPLOAD_FOLDER={}

이 값은 실제 경로가 아니므로 컨테이너에서는 중괄호를 제거해야 한다. 잘못 입력하면 {/app/uploads} 전체가 경로로 해석되어 FastAPI가 시작되지 않는다.

10. Cloudflare D1 API Token

로컬 .env에는 CLOUDFLARE_API_TOKEN이 없었지만 로컬 D1 연결은 정상 동작했다. 로컬에서는 Wrangler 로그인 정보가 fallback으로 사용되고 있었기 때문이다.

하지만 Oracle VM에는 로컬 PC의 Wrangler 인증 파일이 없으므로 D1 REST API를 호출하려면 별도의 API Token이 필요하다.

Cloudflare에서 다음 권한으로 런타임 토큰을 만들었다.

Token name: oracle-fastapi-d1-runtime

Account
  -> D1
      -> Edit

Account Resources는 사용하는 Cloudflare Account 하나로 제한했다. Zone, DNS, Worker, R2 관리 권한은 추가하지 않았다.

R2는 Cloudflare API Token이 아니라 S3 호환 API용 Access Key와 Secret Access Key로 접근한다.

R2_ACCESS_KEY_ID=<r2-access-key-id>
R2_SECRET_ACCESS_KEY=<r2-secret-access-key>

따라서 D1 API Token과 R2 S3 인증키는 서로 다른 용도다.

11. Oracle Docker Compose 구성

Oracle 배포용 Compose 설정은 다음과 같다.

services:
  fastapi:
    build:
      context: ../..
      dockerfile: Dockerfile
    container_name: personal-service-fastapi
    restart: unless-stopped
    env_file:
      - ../../.env
    ports:
      - "127.0.0.1:8000:8000"
    volumes:
      - fastapi-instance:/app/instance

volumes:
  fastapi-instance:

외부 포트를 직접 공개하지 않고 127.0.0.1:8000에만 바인딩했다. 이후 Nginx가 80/443 요청을 받고 내부 FastAPI로 전달하게 된다.

/app/instance는 named volume으로 보존한다. D1이 운영 데이터의 원본이지만, SQLite shadow DB와 페이지뷰 로그가 컨테이너 재생성 때 사라지지 않도록 하기 위해서다.

컨테이너는 다음 명령으로 실행했다.

cp deployment/oracle/docker-compose.yml.example deployment/oracle/docker-compose.yml
docker compose -f deployment/oracle/docker-compose.yml up -d --build

12. 첫 실행 오류와 설정 로더 수정

처음 컨테이너를 실행했을 때 다음 오류가 발생했다.

RuntimeError: Directory '{/app/uploads}' does not exist

원인은 .env에 경로를 다음처럼 입력했기 때문이다.

UPLOAD_FOLDER={/app/uploads}

또한 기존 설정 로더는 기본 uploads/ 디렉터리는 만들고 있었지만 환경변수로 지정된 UPLOAD_FOLDER는 생성하지 않고 있었다.

이 문제를 해결하기 위해 설정 로더를 수정했다.

database = os.environ.get("DATABASE", str(instance_path / "app.db"))
upload_folder = os.environ.get("UPLOAD_FOLDER", str(default_upload_dir))

Path(database).parent.mkdir(parents=True, exist_ok=True)
Path(upload_folder).mkdir(parents=True, exist_ok=True)

서버의 .env도 다음처럼 수정했다.

sed -i 's|^DATABASE=.*|DATABASE=/app/instance/app.db|' .env
sed -i 's|^UPLOAD_FOLDER=.*|UPLOAD_FOLDER=/app/uploads|' .env

이후 최신 코드를 반영하고 컨테이너를 재생성했다.

git pull origin feature/FastAPI-migration
docker compose -f deployment/oracle/docker-compose.yml up -d --build --force-recreate

13. FastAPI와 D1 연결 확인

VM 내부에서 health endpoint를 호출했다.

curl http://127.0.0.1:8000/health

응답은 다음과 같았다.

{
  "ok": true,
  "service": "personal-service-fastapi",
  "repository_backend": "d1",
  "storage_backend": "r2",
  "database_configured": true,
  "database_role": "shadow"
}

database_role이 shadow인 것은 오류가 아니다.

D1 = 운영 데이터 원본
SQLite = 공용 repository helper가 사용하는 로컬 shadow DB

D1 API가 실제로 동작하는지 문서 목록 API도 호출했다.

curl "http://127.0.0.1:8000/api/documents?per_page=1"

이 단계에서 다음 항목을 확인했다.

• Docker 컨테이너 실행
• Uvicorn 프로세스 시작
• FastAPI ASGI 엔트리포인트 로딩
• 환경변수 기반 설정 로딩
• 로컬 shadow SQLite 생성
• Cloudflare D1 API 연결
• FastAPI health endpoint 응답

14. 현재 남은 작업

현재 컨테이너는 127.0.0.1:8000에만 열려 있어 외부 브라우저에서 직접 접근할 수 없다.

다음 순서로 운영 연결을 진행한다.

1. Oracle VM에 Nginx 설치
2. Nginx에서 80/443 -> 127.0.0.1:8000 reverse proxy 설정
3. 가비아에서 구매한 도메인을 Cloudflare에 추가
4. 가비아 네임서버를 Cloudflare 네임서버로 변경
5. Cloudflare DNS에 Oracle VM 공인 IP를 A 레코드로 등록
6. Cloudflare Origin Certificate 또는 공개 인증서 설정
7. Cloudflare SSL/TLS를 Full (strict)로 설정
8. Cloudflare Access 또는 별도 인증으로 서비스 보호

현재 FastAPI API에는 별도 로그인 인증이 없으므로 도메인을 바로 공개하기 전에 접근 제어를 추가해야 한다.

마무리

이번 작업을 통해 FastAPI 애플리케이션을 Oracle VM에서 Docker로 실행하고, Cloudflare D1 연결까지 확인했다.

A1 인스턴스 용량 부족으로 E2.1.Micro를 임시 실행 서버로 선택했지만, 애플리케이션은 Docker와 외부 저장소에 분리되어 있다. 나중에 A1 VM을 새로 만들더라도 같은 이미지와 환경변수로 재배포할 수 있다.

이번 단계에서 확인한 핵심은 다음과 같다.

• FastAPI는 Cloudflare Worker 없이 일반 Docker 서버에서 실행 가능하다.
• Oracle Always Free VM을 애플리케이션 실행 서버로 사용할 수 있다.
• 로컬 Wrangler 인증과 서버용 D1 API Token은 구분해야 한다.
• R2 업로드에는 Cloudflare API Token이 아니라 R2 S3 Access Key가 필요하다.
• 컨테이너 환경에서는 환경변수 경로를 실제 디렉터리로 지정하고 생성해야 한다.
• 실행 서버를 교체해도 D1/R2를 유지하면 애플리케이션 재배포가 단순해진다.

다음 글에서는 Nginx reverse proxy와 가비아 도메인, Cloudflare DNS, HTTPS 연결 과정을 정리할 예정이다.

처음에는 Cloudflare에서 FastAPI까지 실행하는 방법을 검토했다. Cloudflare Container를 사용하면 Docker 기반 FastAPI를 실행할 수 있지만, 현재 기준으로 Container는 Workers Paid 플랜이 필요하다. 무료 티어를 유지하면서 FastAPI를 실행하려면 애플리케이션 실행 서버와 Cloudflare의 저장소 서비스를 분리하는 편이 더 적합했다.

이번 글에서는 Oracle Cloud의 Always Free VM을 생성하고, 이후 Docker 기반 FastAPI 서버를 올릴 수 있는 네트워크 환경을 구성하는 과정을 정리한다.

1. 선택한 운영 구조

이번에 선택한 구조는 다음과 같다.

사용자 브라우저
    -> Cloudflare DNS / Proxy
    -> Oracle Always Free VM
    -> Docker
    -> Uvicorn
    -> FastAPI
    -> Cloudflare D1 / R2

FastAPI 애플리케이션은 특정 Cloudflare 런타임에 맞춰 작성하지 않는다. 일반적인 Docker 컨테이너로 실행하기 때문에 로컬, Oracle Cloud, 다른 VM, 다른 클라우드 환경에서도 같은 이미지를 사용할 수 있다.

Cloudflare는 계속 다음 역할을 담당한다.

• D1: 운영 데이터베이스

• R2: 파일 저장소
• DNS 및 필요한 경우 Proxy

즉, 애플리케이션 실행 환경과 저장소 서비스를 분리한다. 이 구조를 선택하면 무료 실행 환경을 사용할 수 있고, 나중에 서버를 옮길 때 FastAPI 코드와 Dockerfile을 그대로 재사용할 수 있다.

Oracle 공식 문서 기준 Always Free 리소스에는 Ampere A1 Compute가 포함되어 있다. 전체 한도는 월 기준 2 OCPU, 12GB 메모리 수준이며, 계정과 리전에 따라 실제 생성 가능 여부는 달라질 수 있다.

참고: Oracle Always Free 리소스

2. 리전 확인

Oracle Cloud Console에 로그인한 뒤 우측 상단의 리전을 확인한다.

Always Free VM은 기본적으로 계정의 Home Region에서 생성하는 것이 안전하다. 특정 리전에서 Always Free 인스턴스의 호스트 용량이 부족하면 생성 시 Out of host capacity 오류가 발생할 수 있다. 이 경우 같은 리전의 다른 Availability Domain을 선택하거나 잠시 후 다시 시도한다.

3. VCN과 Public Subnet 만들기

VM 생성 화면에서 네트워크를 한 번에 만들 수도 있지만, Public Subnet이 제대로 선택되지 않으면 공인 IPv4를 할당할 수 없다. 그래서 먼저 VCN을 별도로 생성한다.

1. 좌측 상단 메뉴를 연다.
2. Networking을 선택한다.
3. Virtual cloud networks로 이동한다.
4. Start VCN Wizard를 클릭한다.
5. Create VCN with Internet Connectivity를 선택한다.
6. Start VCN Wizard를 클릭한다.

다음 값을 입력한다.

VCN Name: fastapi-vcn
IPv4 CIDR Block: 10.0.0.0/16
Public Subnet CIDR Block: 10.0.1.0/24
Private Subnet CIDR Block: 기본값

VCN 이름은 원하는 이름을 사용해도 된다. CIDR 값은 새 VCN을 만드는 경우 사용할 수 있는 예시값이다.

Create를 클릭하면 Oracle이 다음 네트워크 구성요소를 함께 만든다.

• Virtual Cloud Network
• Internet Gateway
• Route Table
• Public Subnet
• Private Subnet

생성이 끝나면 VCN 상세 화면의 Subnets에서 Public Subnet이 생성되었는지 확인한다. 이후 VM에는 이 Public Subnet을 선택해야 한다.

Oracle에서는 Private Subnet의 리소스에 공인 IPv4 주소를 할당할 수 없다. 공인 IP를 사용하려면 반드시 Public Subnet을 선택해야 한다.

참고: Oracle 인스턴스 생성 문서

4. Compute Instance 생성

1. 좌측 상단 메뉴를 연다.
2. Compute를 선택한다.
3. Instances로 이동한다.
4. Create instance를 클릭한다.

4.1 기본 정보

Name: fastapi-server
Compartment: 기본 Root compartment
Availability Domain: 기본값
Capacity Type: On-demand capacity
Fault Domain: 기본값

Availability Domain은 Always Free Eligible로 표시되는 항목을 우선 선택한다. 화면에 표시되는 항목은 리전마다 다를 수 있으므로 기본 선택값이 Always Free 대상인지 확인한다.

4.2 Image and shape

Image and shape 영역에서 Edit를 클릭한다.

Image는 다음 중 하나를 선택한다.

Ubuntu 24.04
또는
Ubuntu 22.04

그다음 Change shape를 클릭하고 다음처럼 설정한다.

Shape type: Virtual machine
Shape series: Ampere
Shape: VM.Standard.A1.Flex
OCPU: 1
Memory: 6 GB

VM.Standard.A1.Flex가 Always Free-eligible로 표시되는지 확인한 뒤 Select shape를 클릭한다.

이 서비스는 Docker 기반으로 실행할 예정이므로 ARM 기반인 Ampere 인스턴스를 사용해도 된다. 현재 Dockerfile의 Python 기본 이미지는 ARM 환경에서 사용할 수 있는 이미지를 제공한다.

4.3 Primary VNIC 및 네트워크

Primary VNIC 또는 Networking 영역에서 다음과 같이 선택한다.

Virtual cloud network: Select existing virtual cloud network
VCN: fastapi-vcn
Subnet: Select existing subnet
Subnet: Public Subnet
Private IPv4 address: Automatically assign private IPv4 address
Public IPv4 address assignment: Automatically assign public IPv4 address

여기서 가장 중요한 값은 Subnet이다. 반드시 앞에서 만든 Public Subnet을 선택해야 한다.

다음과 같은 경고가 나오면 현재 Subnet이 Public Subnet으로 선택되지 않은 상태다.

You must select a public subnet to assign a public IPv4 address.

이 경우 Private Subnet을 선택했는지 확인하고, Select existing subnet에서 Public Subnet을 다시 선택한다.

Automatically assign public IPv4 address는 인스턴스 생성 시 외부에서 접속 가능한 공인 IPv4 주소를 자동으로 할당하는 옵션이다. SSH 접속과 웹 서비스 공개를 위해 체크한다.

4.4 SSH 키

Add SSH keys 영역에서 다음을 진행한다.

1. Generate a key pair for me를 선택한다.
2. Save Private Key를 클릭한다.
3. 다운로드된 .key 파일을 안전한 위치에 보관한다.
4. 필요하다면 Save Public Key도 함께 저장한다.

Private Key는 분실하면 안 된다. 공개 저장소에 올리거나 다른 사람에게 전달해서도 안 된다.

4.5 Boot Volume

Boot volume 영역은 우선 기본값을 사용한다.

별도 디스크 구성이나 사용자 지정 부트 볼륨은 초기 배포에 필요하지 않다. 나중에 로그, 업로드 파일, 백업 정책을 정리할 때 별도로 검토한다.

5. 인스턴스 생성 및 확인

모든 설정을 확인한 뒤 하단의 Create를 클릭한다.

생성이 끝나면 인스턴스 상세 화면에서 다음 항목을 확인한다.

State: Running
Public IPv4 address: 숫자 형태의 공인 IP
Private IPv4 address: 숫자 형태의 사설 IP

Public IPv4 address가 비어 있다면 다음을 다시 확인한다.

• Subnet이 Public Subnet인지
• Automatically assign public IPv4 address가 체크되어 있는지
• VCN에 Internet Gateway와 Route Table이 생성되어 있는지

6. 80, 443 포트 열기

VCN의 보안 목록에서 웹 접속 포트를 허용한다.

1. VM 상세 화면에서 Primary VNIC를 클릭한다.
2. 연결된 Subnet을 클릭한다.
3. Default Security List를 클릭한다.
4. Add Ingress Rules를 클릭한다.

HTTP 규칙을 추가한다.

Source CIDR: 0.0.0.0/0
IP Protocol: TCP
Destination Port Range: 80

HTTPS 규칙도 추가한다.

Source CIDR: 0.0.0.0/0
IP Protocol: TCP
Destination Port Range: 443

SSH 접속용 22번 포트가 이미 존재하는지도 확인한다. 없다면 다음 규칙을 추가한다.

Source CIDR: 0.0.0.0/0
IP Protocol: TCP
Destination Port Range: 22

운영 환경에서는 SSH를 0.0.0.0/0으로 열어두기보다 본인의 고정 IP로 제한하는 것이 안전하다. 초기 접속 확인 후 보안 규칙을 다시 좁히는 것이 좋다.

7. 다음 작업

VM 생성이 끝났다고 FastAPI가 바로 실행되는 것은 아니다. 다음 순서로 서버를 구성해야 한다.

1. SSH로 Oracle VM 접속
2. Docker 설치
3. 저장소를 VM으로 가져오기
4. 운영용 환경변수 설정
5. Docker 이미지 빌드
6. FastAPI 컨테이너 실행
7. Nginx 또는 Caddy로 80/443 연결
8. Cloudflare DNS에 도메인 연결
9. /health 엔드포인트로 운영 상태 확인

현재 애플리케이션은 Dockerfile에서 uvicorn asgi:app으로 FastAPI를 실행하도록 구성되어 있다. 따라서 Oracle VM에 배포할 때도 Cloudflare Worker 전용 코드가 아니라 일반 Docker 실행 절차를 사용한다.

마무리

이번 단계에서는 애플리케이션을 실행할 무료 인프라를 마련했다. Cloudflare Container는 무료 티어에서 사용할 수 없었지만, Oracle Always Free VM을 사용하면 FastAPI를 특정 클라우드 런타임에 종속시키지 않고 Docker 애플리케이션으로 운영할 수 있다.

이 구조에서는 실행 서버를 다른 VM이나 클라우드로 옮겨도 FastAPI 코드와 Dockerfile을 그대로 재사용할 수 있다. Cloudflare D1과 R2는 저장소 계층으로만 사용하기 때문에 애플리케이션 실행 환경과의 결합도 줄어든다.

다음 글에서는 생성한 Oracle VM에 SSH로 접속하고, Docker를 설치한 뒤 FastAPI 컨테이너를 실행하는 과정을 정리할 예정이다.

1. 실제 마이그레이션 시작

2편까지는 FastAPI로 전환하려는 이유와 작업 순서를 정리했다. 이번 글부터는 실제 코드에서 어떤 부분을 변경했는지 정리해보려고 한다.

이번 작업에서는 Flask 앱을 바로 삭제하지 않고, 기존 Flask 앱은 실행 가능한 상태로 유지하면서 별도의 FastAPI 앱을 추가했다. 이렇게 하면 기존 기능을 참고하면서 API를 하나씩 옮길 수 있고, 문제가 생겼을 때 비교할 수 있는 기준도 남는다.

2. FastAPI 앱 엔트리포인트 추가

FastAPI 앱은 fastapi_app/main.py에서 생성하고, 외부 ASGI 서버가 사용할 수 있도록 asgi.py에서 앱을 노출했다.

from fastapi_app.main import app

로컬에서는 다음과 같이 실행할 수 있다.

uvicorn asgi:app --reload

기존 Flask의 run.py는 바로 삭제하지 않고 호환 실행 경로로 남겨두었다.

3. 설정 로더 분리

기존 Flask 앱은 app.config을 통해 환경변수와 설정값을 전달받았다. FastAPI에서도 같은 설정을 사용해야 하므로 환경변수 로딩 결과를 AppSettings 객체로 분리했다.

Flask는 이 객체를 app.config으로 변환하고, FastAPI는 app.state.settings에 보관하도록 했다. 이 방식으로 설정 로딩과 프레임워크별 앱 초기화를 나눌 수 있었다.

4. Repository provider 이관

기존 프로젝트에는 SQLite와 D1을 분기하는 repository/provider 구조가 이미 있었다. 이 구조를 활용해 FastAPI에서는 요청의 dependency로 repository provider를 받도록 구성했다.

FastAPI Request
  -> dependency
  -> repository provider
      -> SQLite repository
      -> D1 repository

Flask에서만 사용할 수 있었던 provider 생성 로직은 공용 runtime provider로 옮겼다. 이후 Flask 호환 경로도 같은 builder를 사용하도록 변경해 두 런타임의 저장소 선택 로직을 통합했다.

5. 주요 API 이관

기능별로 FastAPI router를 분리했다.

• 대시보드
• 문서
• 에셋
• WBS
• 일정
• 멤버
• 페이지뷰 로그

문서와 에셋 API는 목록·상세·생성·수정·삭제뿐만 아니라 폴더, 태그, 일괄 처리, 업로드·다운로드까지 함께 이관해야 했다.

6. Flask app context 의존성 줄이기

실제 작업에서 가장 시간이 많이 걸린 부분은 Flask decorator를 FastAPI decorator로 바꾸는 일이 아니었다. current_app, g, Flask 전역 설정에 숨어 있던 의존성을 찾아내는 일이 더 중요했다.

DB 연결, storage 설정, 로그 파일 경로를 명시적인 설정 기반 함수로 분리했다. FastAPI는 lifespan에서 연결을 만들고, Flask 호환 함수는 기존 app context에서 동작하도록 유지했다.

7. 파일 처리 이관

파일 업로드는 UploadFile의 stream을 사용하고, local/R2 분기는 storage 계층에서 담당하도록 했다. 라우터에서는 업로드 결과로 object key, 공개 URL, content type, size, checksum을 받아 repository에 메타데이터를 저장한다.

다운로드는 파일 바이트와 Content-Disposition 헤더를 FastAPI Response로 반환하도록 변경했다. 이 덕분에 파일을 브라우저에서 열어버리는 대신 다운로드 응답으로 제어할 수 있었다.

8. 현재까지의 결과

현재 FastAPI는 핵심 API와 프론트엔드 진입 라우팅을 직접 처리할 수 있다. Flask는 아직 제거하지 않았지만, run.py와 기존 blueprint를 호환 경로로 두고 공용 계층부터 Flask 의존성을 줄인 상태다.

다음 글에서는 Docker와 운영 배포 구조, Cloudflare D1/R2 연결, 그리고 Cloudflare Worker를 메인 애플리케이션으로 사용하지 않으면서 Container를 연결하는 방법을 정리할 예정이다.

시작하기

Eletron Forge는 공식적으로 Vite + TypeScript 템플릿을 제공하고 있기 때문에 아래와 같이 프로젝트 셋팅을 진행합니다.

> pnpm create electron-app@latest . --template=vite-typescript

시작부터 삐끗

PS D:\dev\git\dock> pnpm create electron-app@latest . --template=vite-typescript
Downloading typescript@5.4.5: 5.82 MB/5.82 MB, done
Packages are hard linked from the content-addressable store to the virtual store.
  Content-addressable store is at: C:\Users\user\AppData\Local\pnpm\store\v11
  Virtual store is at:             AppData/Local/pnpm/store/v11/links
[ERR_PNPM_EXOTIC_SUBDEP] Exotic dependency "@electron/node-gyp" (resolved via git-repository) is not allowed in subdependencies when blockExoticSubdeps is enabled
This error happened while installing the dependencies of create-electron-app@7.11.2
 at @electron-forge/cli@7.11.2
 at @electron-forge/core-utils@7.11.2
 at @electron/rebuild@3.7.2
[WARN] GET https://registry.npmjs.org/minimist error (UND_ERR_DESTROYED). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/signal-exit error (UND_ERR_DESTROYED). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/globalthis error (UND_ERR_DESTROYED). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/sprintf-js error (UND_ERR_DESTROYED). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/@types%2Fmute-stream error (UND_ERR_DESTROYED). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/@types%2Fwrap-ansi error (UND_ERR_DESTROYED). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/type-fest error (UND_ERR_DESTROYED). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/eslint-scope error (UND_ERR_DESTROYED). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/color-name error (UND_ERR_DESTROYED). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/minimatch error (UND_ERR_DESTROYED). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/bluebird error (unknown). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/glob error (unknown). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/@types%2Fnode error (UND_ERR_DESTROYED). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/es-module-lexer error (unknown). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/enhanced-resolve error (unknown). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/@webassemblyjs%2Fwasm-parser error (unknown). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/acorn error (unknown). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/@webassemblyjs%2Fwasm-edit error (unknown). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/@webassemblyjs%2Fast error (unknown). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/@xmldom%2Fxmldom error (UND_ERR_DESTROYED). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/get-stream error (UND_ERR_DESTROYED). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/@types%2Fyauzl error (UND_ERR_DESTROYED). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/isbinaryfile error (UND_ERR_DESTROYED). Will retry in 10 seconds. 2 retries left.
[WARN] GET https://registry.npmjs.org/browserslist error (unknown). Will retry in 10 seconds. 2 retries left.
.../mrwr9xx4-bsw                         | Progress: resolved 148, reused 0, downloaded 149, added 0

Exotic dependency "@electron/node-gyp" (resolved via git-repository) is not allowed in subdependencies when blockExoticSubdeps is enabled

원인

최신 pnpm은 기본적으로 blockExoticSubdeps: true라서, 하위 패키지가 Git 저장소 같은 비표준 경로의 의존성을 가져오면 차단한다. 그런데 Electron Forge 내부의 @electron/rebuild가 @electron/node-gyp를 Git 의존성으로 사용해서 막힌것이다.

가장 간단한 해결법

프로젝트 생성 단계만 npm으로 진행하자. 현재 폴더에 생성 중 남은 파일이 있는지 먼저 확인한다.

+ 주의사항

절대로 누구처럼 프로젝트 디렉토리에 git init부터 하시면 안됩니다. 프로젝트 root에 .git 디렉토리가 있으면 삭제한 뒤에 프로젝트 설정이 끝나면 다시 설정하시는걸 권장드립니다.

Get-ChildItem -Force

중간 생성물이 없다면 그대로 실행한다.

npm init electron-app@latest . -- --template=vite-typescript

또는

npx create-electron-app@latest . --template=vite-typescript

생성 후

npm start

Electron 창이 뜨면 Electron 프로젝트 셋팅은 성공

pnpm은 버려야 하냐?

아닙니다. 프로젝트 생성만 npm으로 하고, 생성된 뒤 pnpm으로 전환할 수 있습니다.

생성 완료 후

Remove-Item package-lock.json
pnpm install
pnpm start

다만 같은 오류가 다시 발생할 수 있어서, 당장은 이 프로젝트는 npm으로 통일하는 게 가장 편한 길입니다.

Electron Forge와 네이티브 모듈 쪽은 npm 기준 자료와 검증 사례가 많아서, MVP 단계에서는 굳이 패키지 매니저 문제까지 같이 해결할 필요까진 없을 것 같습니다.

pnpm을 반드시 유지하고 싶다면

전역 설정을 끄는 방법도 있습니다.

pnpm config set block-exotic-subdeps false --global

확인

pnpm config get block-exotic-subdeps

그다음 다시

pnpm create electron-app@latest . --template=vite-typescript

하지만 이 설정은 pnpm이 제공하는 공급망 보안 기능을 전역으로 비활성화 합니다. 그래서 개인적으로는 추천하는 방법은 아닙니다. blockExoticSubdeps는 하위 의존성이 Git URL이나 직접 tarball URL을 사용하는 것을 막기 위한 설정입니다.

추천하는 진행 방법

현재 Windows 환경에서 개발을 진행하기 때문에 Powershell 기준으로 작성하고 있습니다. Linux 또는 macOS 환경에서 개발을 진행하실 분들은 해당 내용을 AI Agent에게 질의하여 진행하시면 될 것 같습니다.

cd ~/{workspace_path}/

Get-ChildItem -Force

npx create-electron-app@latest . --template=vite-typescript

npm start

정리하면 pnpm 최신 보안 정책과 Electron Forge 의존성 구조가 충돌한 상황입니다.

• 개인 서비스 개발 프로젝트를 Flask로 운영해 왔다.
• React 프론트, SQLite/D1, local/R2가 공존하는 상태가 되었다.
• PythonAnywhere 이슈와 Cloudflare 이관 고민이 겹쳤다.
• 그런데 Cloudflare Worker 중심으로 가면 벤더 종속성이 커질 수 있다는 고민이 생겼다.

2. 선택지 비교

• Flask 유지
• Cloudflare Worker 중심 전환
• 범용 FastAPI 앱으로 재구성

여기서 핵심 비교 포인트는:

• 로컬 실행 가능성
• 타 클라우드 이식성
• 코드 재사용성
• 포트폴리오 가치

3. 현재 구조 분석

• app/는 Flask 서버
• frontend/는 React SPA
• worker-python/는 Cloudflare Worker 실험 코드
• repository/provider 패턴과 storage 분기 덕분에 완전한 레거시는 아니었다

4. FastAPI를 선택한 이유

• ASGI 기반
• 범용 배포
• 타입 기반 API 설계
• 문서화/설명력
• 이미 프로젝트 내부에 일부 FastAPI 경험이 존재
• AI 기능 연동 고려

5. 마이그레이션 전략

• 새 FastAPI 앱을 병렬로 세운다
• 공통 기반부터 분리한다
• JSON API부터 옮긴다
• 파일 처리와 프론트 서빙을 뒤에 옮긴다

6. 첫 단계에서 한 일

• 공통 설정 로더 분리
• SQLite 초기화 로직의 Flask 의존 완화
• FastAPI 앱 골격 생성
• migration 문서화 시작

7. 앞으로 남은 일

• CRUD API 본 이전
• 업로드/다운로드 이식
• 프론트 라우팅 이전
• seed/init/운영 명령 재정리

8. 회고 포인트

• 프레임워크 교체는 “문법 치환”이 아니라 “구조 재정의”였다
• app context 제거가 예상보다 큰 작업 단위였다
• 이식성을 원하면 런타임보다 코어 아키텍처를 먼저 봐야 했다

꽤 긴 시간동안 포스트를 하지 못했다. 이런 저런 이유가 있겠지만 가장 큰 이유 2가지는 업무와 건강상의 이유로 공백이 꽤나 길어졌다. 지난 몇년간 업무상으로 익힌 여러 스킬들이 있고, 예전의 포스팅들을 보며 "내 과거가 이랬었구나. 지금이랑은 많이 다르구나"를 많이 느끼고, 개발이라는 업무 환경만 놓고 보더라도 참 많이 변했음을 느낀다. 그동안 서비스 회사에서 ASP.NET Core, Python 등으로 백엔드 업무를 진행했고, 간간히 요청이 오면 프론트 작업까지 병행하기도 했다. 이후 여러가지 많은 일들이 있었지만 다시 마음을 다잡고 미래의 내가 지금의 나를 다시 돌아볼 수 있는 포스팅을 다시 이어가고자 한다.

최근에는 지인이 개발 요청을 준 사항이 있어서 간단한 프로젝트를 진행중이다. 특정 도메인을 언급할 순 없지만 AI와 협업하는 AI-Human coWorking 시스템을 개발했고 지속적으로 고도화 중이다.

초반 구축 과정에선 간단한 구현만 진행하는 것으로 설계하여 Flask 프레임워크를 채택하여 문서/일정/WBS/멤버 관리 등 일반적인 업무에 사용하는 내용만 생각했는데, 해당 내용들을 완성하고 보니 AI Agent를 통해서 기획 문서를 공유하고 AI Agent가 일부 페어 프로그래밍을 진행할 수 있을만한 포인트를 확인하여 최근 AI 서비스에서 많이 채택하는 FastAPI로 전체 서비스 이관을 진행할 예정이다.

현재 구조 정리

1. 현재 앱의 성격

이 프로젝트는 처음에는 Flask 기반의 개인 서비스 개발 프로젝트로 시작했다.
문서, 에셋, WBS, 일정, 멤버 관리 기능이 한 애플리케이션 안에 모여 있으며, 최근에는 Cloudflare D1/R2 이관과 React 프론트 전환이 함께 진행되었다.

"왜 CloudFlare를 사용했는가?"라고 궁금증이 생길 수 있다. 물론 GCP나 AWS 등의 서비스도 검토 대상에 두었지만, 현재 상용화 서비스가 아닌 서비스 구현을 위한 실험적인 단계이기 때문에 인프라 비용이 발생하지 않는 CloudFlare와 Pythonanywhere을 채택했다.

현재 구조는 크게 세 축으로 볼 수 있다.

• app/
  • 기존 Flask 서버
• frontend/
  • React 기반 프론트엔드
• worker-python/
  • Cloudflare Python Worker 실험/이행용 서버 코드

2. Flask 서버의 현재 역할

현재 Flask 서버는 아래 역할을 동시에 맡고 있다.

• JSON API 제공
• React 빌드 결과 정적 서빙
• 로컬 업로드 파일 서빙
• SQLite 초기화와 seed 명령 제공
• D1/R2를 포함한 하이브리드 런타임 설정 관리

즉, 전통적인 서버 역할과 임시 운영 보조 기능이 한곳에 모여 있다.

3. 구조적으로 좋은 점

• repository/provider 패턴이 이미 존재한다.
• SQLite와 D1을 추상화하려는 시도가 들어가 있다.
• 스토리지도 local/R2를 분기할 수 있게 되어 있다.
• React 프론트가 분리되어 있어 API 서버 교체가 상대적으로 쉬운 편이다.

이 점들은 FastAPI 마이그레이션에 매우 유리하다.

4. 현재 구조의 제약

4-1. Flask app context 의존

다음 요소들이 Flask 내부 전역 컨텍스트에 기대고 있다.

• current_app
• g
• Blueprint
• jsonify
• send_from_directory
• send_file

이 의존성은 프레임워크 전환 시 가장 먼저 정리해야 하는 대상이다.

4-2. 실행 환경 결합도

현재 서버는 아래를 한 앱에서 직접 처리한다.

• 로컬 SQLite 파일
• instance/ 기반 로그 파일
• uploads/ 기반 파일 서빙
• Cloudflare D1/R2 설정

이 자체가 문제는 아니지만, 범용 배포를 목표로 할 때는 실행환경 의존을 좀 더 드러내고 분리해야 한다.

4-3. Worker 실험 코드와 본 서버 코드의 분리

worker-python/은 FastAPI 기반이지만 Cloudflare Worker 런타임을 전제로 한다.
즉, FastAPI 경험은 이미 일부 축적되어 있지만, 그 코드가 곧바로 “범용 서버”를 의미하지는 않는다.

5. 현재 구조를 한 문장으로 요약하면

Flask 중심의 실서비스 서버와 Cloudflare 전환 실험 코드가 공존하고 있으며, 핵심 도메인 로직은 꽤 재사용 가능하지만 프레임워크/런타임 결합을 더 느슨하게 만들어야 한다.

FastAPI 전환 의도

1. 왜 지금 Flask에서 FastAPI로 옮기려고 하는가

이번 전환의 목적은 “Flask가 나쁘다”가 아니다.
핵심은 이 서비스가 특정 런타임이나 호스팅 환경에 잠기지 않게 만드는 것이다.

현재 운영 리스크와 방향성은 아래처럼 정리된다.

• PythonAnywhere 서비스 불안정성 이슈가 발생했다.
• Cloudflare Worker는 매력적이지만, 장기적으로는 Cloudflare 전용 코드 비중이 커질 수 있다.
• 로컬 개발, 다른 클라우드, 확장성을 모두 고려하면 범용 ASGI 앱이 더 적합하다.
• 또한 LLM을 적용 등 AI 개발 방법론을 채택하기엔 Flask보단 FastAPI가 적합하다는 생각을 했다.

2. FastAPI가 이번 상황에 맞는 이유

• ASGI 표준 기반이라 이식성이 좋다.
• 로컬, VPS, Docker, Render, Fly.io, Railway, ECS 등 다양한 환경으로 옮기기 쉽다.
• JSON API 중심 앱에 잘 맞는다.
• 타입 힌트와 문서화 측면에서 사용성이 높다.
• 이미 프로젝트 내부에 FastAPI 경험(worker-python/)이 일부 있다.
• AI 기능을 도입할 부분이 있다.

3. 이번 마이그레이션의 진짜 목표

3-1. 기술 목표

• Flask app context 의존 제거
• 범용 FastAPI 앱 코어 확보
• 저장소/스토리지/설정 계층의 프레임워크 독립성 강화
• JSON API 우선 이전

3-2. 운영 목표

• 로컬 실행 경로 단순화
• 특정 호스팅 벤더 의존도 완화
• 추후 Docker 기반 배포도 가능한 구조 확보

3-3. 목표

• “기능 구현”만이 아니라 “서비스 구조 재설계” 경험을 남긴다.
• 레거시 Flask 앱을 분석하고 ASGI 구조로 이행한 과정을 정리한다.
• 단순 CRUD가 아니라 저장소 추상화, 스토리지 전략, 런타임 이식성 문제를 함께 설명한다.

4. 무엇을 하지 않으려는가

• Cloudflare Worker 전용 구조를 메인 아키텍처로 삼지 않는다.
• 프레임워크 이름만 바꾸는 기계적 치환은 하지 않는다.
• 한 번에 모든 코드를 뒤엎는 빅뱅 전환은 피한다.

5. 전환 전략 한 줄 요약

기존 Flask 앱 옆에 범용 FastAPI 앱을 세우고, 공통 기반을 분리한 뒤 API부터 단계적으로 이전한다.

Android Size Unit

안드로이드 위젯의 크기를 지정할 때 사용되는 단위에 대한 정리 안드로이드 크기 단위에는 총 6가지(dp, in, mm, pt, px, sp)가 있다. 위젯의 크기를 설정할 때는 wrap_content, match_parent 또는 dp를 사용. 텍스트 사이즈는 sp 단위를 사용하는 것을 권고.

1. px (pixel) 실제 픽셀 수를 뜻합니다. px을 이용하면 해상도가 다른 디바이스마다 실제 크기가 다르게 보이며 심지어 이미지가 깨질 수도 있습니다. 2. dp / dip (Density Independent Pixel) 화면의 크기를 기준으로 하며, 어떠한 화면의 해상도에도 같은 비율로 출력해줍니다. px만으로 다양한 디바이스의 해상도를 지원할 수 없기 때문에 자주 쓰입니다. 3. dpi (Dots per Inch) 1인치에 들어있는 픽셀 수를 뜻하며, 안드로이드에서는 160을 기본으로 합니다. 4. sp / sip (Scale Independent Pixel) 글꼴의 단위로 자주 쓰입니다. dp와 비슷하지만 사용자가 선택한 글꼴에 따라 달라집니다. 5. in (Inch) 실제 물리적인 길이(2.54cm)입니다. 6. mm (milli meter) 네. 생각하시는 그 mm 맞습니다. 실제 물리적인 길이입니다. 7. em 글꼴과 상관 없이 동일한 텍스트의 크기를 출력합니다.
[참조] [Android Studio] 길이 단위 - dp, dpi, px, sp 의 차이점 [참조] 안드로이드 크기 단위(dp, sp, pt, px, mm, in)

LinearLayout

Orientation(Horizontal)

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity"
    android:orientation="horizontal">
    <TextView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:text="TextView1"
        android:layout_weight="1"
        android:background="#ff9966"
        android:layout_margin="5dp"
        />
    <TextView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:text="TextView2"
        android:layout_weight="1"
        android:background="#66ffcc"
        android:layout_margin="5dp"
        />
    <TextView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:text="TextView3"
        android:layout_weight="1"
        android:background="#99ff00"
        android:layout_margin="5dp"
        />
    <TextView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:text="TextView4"
        android:layout_weight="1"
        android:background="#cc00ff"
        android:layout_margin="5dp"
        />
</LinearLayout>

Result

Orientation(Vertical)

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity"
    android:orientation="vertical">
    <TextView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:text="TextView1"
        android:layout_weight="1"
        android:background="#ff9966"
        android:layout_margin="5dp"
        />
    <TextView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:text="TextView2"
        android:layout_weight="1"
        android:background="#66ffcc"
        android:layout_margin="5dp"
        />
    <TextView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:text="TextView3"
        android:layout_weight="1"
        android:background="#99ff00"
        android:layout_margin="5dp"
        />
    <TextView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:text="TextView4"
        android:layout_weight="1"
        android:background="#cc00ff"
        android:layout_margin="5dp"
        />
</LinearLayout>

Result

RelativeLayout

Target base

layout_to[location]Of="[target]" : [target]의 [location] 지정 location : Right, Left, above, below, StartOf, EndOf

layout_align[location]="[target]" : [target]의 [location] 기준 정렬 location : Right, Left, Top, Bottom, Baseline

View base

TableLayout

<TableLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity"
    >
    <TableRow
    android:layout_height="0dp"
    android:layout_weight="1"
    android:background="#FF0000">
    <TextView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:text="Row1 Textview1"
        android:layout_weight="1"
        android:background="#ff9966"
        android:layout_margin="5dp"
        />
    <TextView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:text="Row1 Textview2"
        android:layout_weight="1"
        android:background="#6600cc"
        android:layout_margin="5dp"
        />
    <TextView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:text="Row1 Textview3"
        android:layout_weight="1"
        android:background="#66ffdd"
        android:layout_margin="5dp"
        />
    <TextView
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:text="Row1 Textview4"
        android:layout_weight="1"
        android:background="#3355cc"
        android:layout_margin="5dp"
        />
</TableRow>
    <TableRow
        android:layout_height="0dp"
        android:layout_weight="1">
        <TextView
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            android:text="Row2 Textview1"
            android:layout_weight="1"
            android:background="#99ff00"
            android:layout_margin="5dp"
            />
        <TextView
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            android:text="Row2 Textview2"
            android:layout_weight="1"
            android:background="#cc00ff"
            android:layout_margin="5dp"
            />
    </TableRow>
</TableLayout>

Result

ConstraintLayout

<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    tools:context=".MainActivity">
    <TextView
        android:id="@+id/t1"
        android:layout_width="75dp"
        android:layout_height="75dp"
        android:text="TextView1"
        app:layout_constraintLeft_toLeftOf="parent"
        app:layout_constraintRight_toRightOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintBottom_toBottomOf="parent"
        android:background="#ff9966"
        />
    <TextView
        android:layout_width="75dp"
        android:layout_height="75dp"
        android:text="TextView2"
        app:layout_constraintCircle="@+id/t1"
        app:layout_constraintCircleRadius="150dp"
        app:layout_constraintCircleAngle="140"
        android:background="#66ffcc"
        />
    <TextView
        android:layout_width="75dp"
        android:layout_height="75dp"
        android:text="TextView3"
        app:layout_constraintCircle="@+id/t1"
        app:layout_constraintCircleRadius="150dp"
        app:layout_constraintCircleAngle="190"
        android:background="#99ff00"
        />
    <TextView
        android:layout_width="75dp"
        android:layout_height="75dp"
        android:text="TextView4"
        app:layout_constraintLeft_toRightOf="@id/t1"
        app:layout_constraintTop_toTopOf="@id/t1"
        android:background="#cc00ff"
        />
</androidx.constraintlayout.widget.ConstraintLayout>

Result

Docker 사용빈도가 예상보다 높지 않아서 그런지 자주 쓰는 커맨드를 제외하곤 항상 구글링을 한다. 매번 검색해서 찾아서 쓰는것도 나쁘진 않지만 이번 기회에 체계적으로 정리해서 내가 보고싶을때 마다 보기 위해 이 포스팅을 작성한다. Docker와 Docker Hub를 이용해서 nginx 컨테이너를 생성부터 삭제까지 중간 중간 어떤 커맨드를 사용하는지 적어본다.

intro

Docker는 기본적으로 Root 권한이 필요하다. Docker 내부에서 Root directory에 접근할 권한이 없기 때문이다. 그래서 대부분 privileged=true 옵션을 사용한다고 하는데, 해당 옵션은 보안 문제가 있을 수 있으니 참고하기 바란다. Docker가 정상적으로 설치되었는지 확인해보자.

$ sudo su
$ docker version

혹시나 Docker를 설치했음에도 불구하고 위 스크립트가 정상적으로 실행되지 않는 경우에는 아래 과정을 진행하시길 바란다. 아래 과정은 현재 사용자 계정을 Docker 그룹에 추가하는 과정이다.

Docker group 확인

$ cat /etc/group | grep docker
docker:x:998:

Docker 그룹이 생성되어있지 않다면 아래 명령어로 Docker 그룹을 생성한다.

$ sudo groupadd docker

사용자 추가

Docker 그룹에 사용자를 추가한다.

$ sudo usermod -aG docker <userName>

Docker group init

현재 그룹을 Docker 그룹으로 변경하고 다시 버전을 확인한다.

$ newgrp docker
$ docker version

Docker-hub

Docker-Hub에는 무수히 많은 컨테이너들이 존재한다. 마이크로소프트와 같은 대형 회사에서 기본적으로 제공해주는 컨테이너, 일반 사용자들이 특수한 목적을 위해 구성해놓은 컨테이너, 개인 목적으로 업로드된 컨테이너 등등..

이러한 컨테이너들을 어떻게 야무지게 사용하느냐에 따라서 의미없는 에너지 낭비를 피할 수 있다. 예시로 nginx 컨테이너 이미지를 다운로드하여 실행해보도록 하자.

$ docker search
NAME                              DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
nginx                             Official build of Nginx.                        15928     [OK]
jwilder/nginx-proxy               Automated Nginx reverse proxy for docker con…   2101                 [OK]
richarvey/nginx-php-fpm           Container running Nginx + PHP-FPM capable of…   820                  [OK]
jc21/nginx-proxy-manager          Docker container for managing Nginx proxy ho…   288
linuxserver/nginx                 An Nginx container, brought to you by LinuxS…   160
tiangolo/nginx-rtmp               Docker image with Nginx using the nginx-rtmp…   147                  [OK]
...

nginx를 검색해본 결과 공식으로 제공되는 이미지가 있고, 그 외에 일반 사용자들이 업로드해놓은 이미지들이 있다. 공식으로 제공되는 nginx 이미지를 다운로드하자.

docker images

$ docker images
REPOSITORY    TAG       IMAGE ID       CREATED        SIZE

docker images 명령어를 통해 현재는 보유한 이미지를 확인할 수 있다.

image download directory

다운로드된 이미지는 /var/lib/docker/overlay2에 저장된다.

image download

컨테이너 이미지를 다운로드 하는 커맨드는 docker pull <IMAGENAME>:<VERSION>이다. 버전을 생략할 경우 최신 버전으로 다운로드된다.

$ docker pull nginx

Using default tag: latest
latest: Pulling from library/nginx
e5ae68f74026: Pull complete
21e0df283cd6: Pull complete
ed835de16acd: Pull complete
881ff011f1c9: Pull complete
77700c52c969: Pull complete
44be98c0fab6: Pull complete
Digest: sha256:9522864dd661dcadfd9958f9e0de192a1fdda2c162a35668ab6ac42b465f0603
Status: Downloaded newer image for nginx:latest
docker.io/library/nginx:latest

따로 <VERSION>을 선택하지 않았기 때문에 latest 버전으로 설치된다.

$ docker images

REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
nginx        latest    f652ca386ed1   13 days ago   141MB

$ sudo ls -alFh /var/lib/docker/overlay2/
total 36K
drwx--x---  9 root root 4.0K Dec 16 02:02 ./
drwx--x--- 13 root root 4.0K Dec 14 00:53 ../
drwx--x---  3 root root 4.0K Dec 16 02:02 11a95abfa3e2b45cab9113eb447d98abc70b6e1a84f9435cea419c811f147b1c/
drwx--x---  4 root root 4.0K Dec 16 02:02 2d471323df269aeaff19c810a186cf36e48e3034031cbab8c03ed89e6302fb8e/
drwx--x---  4 root root 4.0K Dec 16 02:02 8235dae3e16fe4df2032d1ab2fd49c3215e173109743502715bd1f61b49c2bbe/
drwx--x---  4 root root 4.0K Dec 16 02:02 8d5040887ffef2eaeae14466a20691aaa2bb220fcc1b0e368b361ee2799b79c6/
drwx--x---  4 root root 4.0K Dec 16 02:02 9ea30971c486bc54be8175e72cb8dac86e08928a4a49dace099748bdd4da7e74/
drwx--x---  4 root root 4.0K Dec 16 02:02 c7422c3c00ac2ff7487fd66d50407f796e316436e7779fede1e3244bbcf80c1b/
drwx------  2 root root 4.0K Dec 16 02:02 l/

docker images, sudo ls -alFh /var/lib/docker/overlay2로 컨테이너 이미지 정상 다운로드를 확인한다. (다운로드가 안되는 경우는 드물다. 그냥 알아두기만 하자.)

작성중...

AWS EC2 Ubuntu 서버에 ASP.NET Core 업로드 테스트를 진행중이다. 서버는 Ubuntu 18.04 LTS이며, 모든 작업은 CLI 환경에서 진행했다.

Why Docker?

도커(Docker)는 리눅스의 응용 프로그램들을 소프트웨어 컨테이너 안에 배치시키는 일을 자동화하는 오픈 소스 프로젝트이다. - 위키백과

그렇게 어려운 말로 적혀있는건 아닌데, 모르는 사람이 들으면 이게 무슨 소리인가 싶을거다. 어느정도 현실에 빗대어 이야기하자.

어떤 API 서버를 구축했고, 클라우드 서비스를 통해 배포 해야한다.

이 상황에서 모든 클라우드 플랫폼이 동일한 환경을 가지고 있지 않고, 개발 당시의 환경과도 다르기 때문에 개발된 환경과 동일한 환경이 클라우드상에도 설정되어야 한다. 서비스가 정상적으로 운영되기 위한 모든 환경을 규격화하는 것이다. 이렇게 규격화된 환경은 차후 다른 서비스를 개발하거나, 유사한 서비스를 개발할 때 시간(자원)을 아껴주는 역할을 한다.

Docker의 가장 큰 장점은 변경 불가능한 인프라(Immutable Infrastructure)이다. 소프트웨어는 자주 수정된다면 여러가지 오류가 발생한다. 특히 변경에 따른 이력관리도 매우 중요한데 Docker는 서버를 구축한 이후 변경이나 업데이트를 할 수 없다. 위와 같은 이유로 인해 Docker는 업데이트 개념이 아닌 서버를 통째로 바꾸는 개념이다. 서버를 업데이트 하기 위해 새로운 도커 이미지를 업데이트해서 컨테이너에 담는다. 불편하다고 생각이 들 수 있겠지만 자잘한 소프트웨어 업데이트로 인해 머리를 쥐어 뜯는것보다 변경하기 위한 이미지를 올리는 것으로 배포를 끝낼 수 있다.

Install Docker Engine on Ubuntu

아래 방법은 repository를 이용한 설치법이다. package를 이용하여 Docker를 설치하려면 Install from a package - Docker Engine 를 참고하길 바란다.

Uninstall old versions

혹시 이전에 설치했던 Docker가 있을 경우를 대비하여 사전에 지워주도록 하자.

$ sudo apt-get remove docker docker-engine docker.io containerd runc

Reading package lists... Done
Building dependency tree
Reading state information... Done
Package 'docker-engine' is not installed, so not removed
Package 'docker' is not installed, so not removed
Package 'containerd' is not installed, so not removed
Package 'docker.io' is not installed, so not removed
Package 'runc' is not installed, so not removed
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.

Set up the repository

1. apt를 업데이트하고, https를 통해 리포지토리를 쉽게 사용할 수 있도록 패키지를 설치한다.

   $ sudo apt-get update
   $ sudo apt-get install ca-certificates curl gnupg lsb-release

2. Docker 공식 GPG Key를 추가한다. ```bash $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

-----BEGIN PGP PUBLIC KEY BLOCK-----

mQINBFit2ioBEADhWpZ8/wvZ6hUTiXOwQHXMAlaFHcPH9hAtr4F1y2+OYdbtMuth lqqwp028AqyY+PRfVMtSYMbjuQuu5byyKR01BbqYhuS3jtqQmljZ/bJvXqnmiVXh 38UuLa+z077PxyxQhu5BbqntTPQMfiyqEiU+BKbq2WmANUKQf+1AmZY/IruOXbnq ... YT90qFF93M3v01BbxP+EIY2/9tiIPbrd =0YYh -----END PGP PUBLIC KEY BLOCK-----

추가된 gpg key는 `/usr/share/keyrings`에 저장된다. 열어볼 필요 없다. 어차피 읽지도 못한다.

3. `stable` 리포지토리를 설정하는 경우 아래와 같이 작성하고, `nightly` or `test` 버전을 원하는 경우 `stable` 대신에 `nightly` or `test`를 넣어주면 된다.
```bash
$ echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Docker Engine

1. 위에서 설정한 리포지토리를 업데이트

   $ sudo apt-get update
   

Hit:1 http://ap-northeast-2.ec2.archive.ubuntu.com/ubuntu bionic InRelease Hit:2 http://ap-northeast-2.ec2.archive.ubuntu.com/ubuntu bionic-updates InRelease Hit:3 http://ap-northeast-2.ec2.archive.ubuntu.com/ubuntu bionic-backports InRelease Get:4 https://download.docker.com/linux/ubuntu bionic InRelease [64.4 kB] Get:5 https://download.docker.com/linux/ubuntu bionic/stable amd64 Packages [22.5 kB] Get:6 https://download.docker.com/linux/ubuntu bionic/nightly amd64 Packages [59.8 kB] Get:7 http://security.ubuntu.com/ubuntu bionic-security InRelease [88.7 kB] Fetched 236 kB in 2s (153 kB/s) Reading package lists... Done

2. `docker-ce`, `docker-ce-cli`, `containerd.io`를 설치한다.
```bash
$ sudo apt-get install docker-ce docker-ce-cli containerd.io
Reading package lists... Done
Building dependency tree
Reading state information... Done
...

설치가 완료되었고, stable repository에서 가장 최신 버전으로 설치되었다. 특정 버전을 설치해야되는 경우에는 apt-cache 명령어를 사용해서 원하는 버전을 설치한다.

$ apt-cache madison docker-ce

 docker-ce | 5:20.10.12~3-0~ubuntu-bionic | https://download.docker.com/linux/ubuntu bionic/stable amd64 Packages
 docker-ce | 5:20.10.11~3-0~ubuntu-bionic | https://download.docker.com/linux/ubuntu bionic/stable amd64 Packages
 docker-ce | 5:20.10.10~3-0~ubuntu-bionic | https://download.docker.com/linux/ubuntu bionic/stable amd64 Packages
 ...
 docker-ce | 18.06.1~ce~3-0~ubuntu | https://download.docker.com/linux/ubuntu bionic/stable amd64 Packages
 docker-ce | 18.06.0~ce~3-0~ubuntu | https://download.docker.com/linux/ubuntu bionic/stable amd64 Packages
 docker-ce | 18.03.1~ce~3-0~ubuntu | https://download.docker.com/linux/ubuntu bionic/stable amd64 Packages

 $ sudo apt-get install docker-ce=<VERSION_STRING> docker-ce-cli=<VERSION_STRING> containerd.io

만약 5:20.10.10~3-0~ubuntu-bionic 버전을 설치하고 싶은 경우

$ sudo apt-get install docker-ce=5:20.10.10~3-0~ubuntu-bionic docker-ce-cli=5:20.10.10~3-0~ubuntu-bionic containerd.io

<VERSION_STRING>에 원하는 버전을 입력해서 설치하면 된다.

Test

동작하는지 확인은 해봐야하니까 hello-world 컨테이너를 실행해보자. 로컬에 hello-world라는 컨테이너가 없으니 Docker Hub에서 자동으로 컨테이너를 다운받아 실행된다.

$ sudo docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
2db29710123e: Pull complete
Digest: sha256:cc15c5...4f685
Status: Downloaded newer image for hello-world:latest

제대로 실행된건지 확인하기 위해 docker ps -a 명령어 실행(sudo 권한으로 해야함)

$ sudo docker ps -a
CONTAINER ID   IMAGE         COMMAND    CREATED          STATUS                      PORTS     NAMES
e42a5f4182f1   hello-world   "/hello"   29 seconds ago   Exited (0) 29 seconds ago             competent_joliot

$ systemctl status docker

정상적으로 실행되고 있음을 확인할 수 있다.

Ending

일주일에 적어도 한 번은 적어보려고 노력하는데 그게 생각처럼 쉽지가 않다.

앞으로 기록할 것들

• AWS Lambda에 업로드한 코드 수정하기(json parsing)
• dotnet publish 패키지 증발 현상
• AWS Lambda 함수와 AWS API Gateway 연동하기
• AWS EC2 ubuntu에 Docker 환경 구축하기 + ASP.NET Core Docker Image

꼼꼼하게 확인해가면서 배우는 습관을 들여야겠다.

AWS Lambda에 .NET Core 프로젝트를 배포하는 과정을 적어볼 예정이다.

AWS Toolkit for Visual Studio

AWS 공식 문서를 참고하여 진행한다. AWS에서는 Visual Studio 2017/2019에 대한 공식 문서만 제공하고 있다. Visual Studio 2022(이하 VS2022)는 아직 공식 문서가 작성되진 않았지만, VS2022를 지원하는 AWS Toolkit Preview는 제공되고 있으니 일단 설치해보기로 한다.

> AWS Toolkit for Visual Studio Download

AWS Toolkit download & install

위에서 언급한 내용대로 VS2022로 설치한다. [install] 버튼 1회만 클릭하면 그리 오래걸리지 않는 시간내에 설치가 완료된다. 솔직히 카톡 PC버전 설치보다 쉬운듯.

Basic AWS Lambda Project

설치가 완료된 상태에서 VS2022를 실행하게 되면 AWS 관련 템플릿들이 추가된 것을 볼 수 있다.

징그럽게 많다..

AWS Lambda Project (.NET Core - C#)를 선택하고 프로젝트의 이름과 위치를 지정한다.

만들기를 클릭하면 위와 같이 Blueprint를 선택하는 창이 뜨는데 당황하지말고 Empty Function을 선택하면 된다.

AWS IAM 콘솔에서 발급받은 Access Key와 Secret Key를 입력하고 Save 하면 된다. 혹시나 Secret Key를 분실한 경우 새로 발급받아야함.

[참고] AWS 자격 증명 프로필 생성 문서

정상적으로 연결되었다면 좌측에 AWS Explorer에 서비스들이 출력된다. 혹시나 여기서도 AWS Explorer가 생성되지 않았다면 [보기] -> [AWS Explorer] 또는 Ctrl + K, A 숏컷을 사용하면 된다.

솔루션 탐색기에 aws-lambda-tools-defaults.json, Function.cs 파일이 있는데 해당 파일 설명은 AWS 공식 문서를 보는게 좋을 것 같다.

aws-lambda-tools-defaults.json

프로젝트의 일부로 생성된 파일을 보여줍니다. Lambda 도구가 기본적으로 읽는 이 파일의 필드를 사용하여 빌드 옵션을 설정할 수 있습니다. Visual Studio의 프로젝트 템플릿에는 기본값이 있는 이러한 필드가 많이 포함되어 있습니다. function-handler 필드는 Lambda 함수가 실행될 때 실행되는 메서드를 지정합니다. 함수 핸들러를 지정하는 경우 필드는 게시 마법사에 미리 채워져 있습니다. 함수, 클래스 또는 어셈블리의 이름을 바꾸면 aws-lambda-tools-defaults.json 파일의 필드도 업데이트해야 합니다.

{
  "Information": [
    "This file provides default values for the deployment wizard inside Visual Studio and the AWS Lambda commands added to the .NET Core CLI.",
    "To learn more about the Lambda commands with the .NET Core CLI execute the following command at the command line in the project root directory.",
    "dotnet lambda help",
    "All the command line options for the Lambda command can be specified in this file."
  ],
  "profile": "",
  "region": "",
  "configuration": "Release",
  "framework": "netcoreapp3.1",
  "function-runtime": "dotnetcore3.1",
  "function-memory-size": 256,
  "function-timeout": 30,
  "function-handler": "AWSLambda_basic::AWSLambda_basic.Function::FunctionHandler"
}

Function.cs

Lambda 함수로 노출할 C# 함수를 정의합니다. 이것은 FunctionHandlerLambda 함수가 실행될 때 실행되는 Lambda 기능입니다. 이 프로젝트에는 입력 텍스트 FunctionHandler를 호출하는 하나의 함수가 정의되어 ToUpper()있습니다.

// Function.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

using Amazon.Lambda.Core;

// Assembly attribute to enable the Lambda function's JSON input to be converted into a .NET class.
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

namespace AWSLambda_basic
{
    public class Function
    {

        /// <summary>
        /// A simple function that takes a string and does a ToUpper
        /// </summary>
        /// <param name="input"></param>
        /// <param name="context"></param>
        /// <returns></returns>
        public string FunctionHandler(string input, ILambdaContext context)
        {
            return input?.ToUpper();
        }
    }
}

Test

가장 기본적인 테스트만 진행할 계획이였기 때문에 Function.cs에 기본적으로 작성되어있는 ToUpper() 기능으로 테스트를 진행할 예정이다.

AWS Explorer에서 AWS Lambda 우클릭 후 Publish to AWS Lambda 선택 실제로 프로젝트 진행시에는 .NET Core v3.1을 사용할 계획은 없지만 이번에는 반항하지 않고 AWS 공식 문서에서 시키는데로 따라해본다. VS2019, VS2017과는 아주 조금 다른 창이 뜨는데 엄청 많이 다른건 아니니까 요령껏 작성했다. 다음 페이지에선 크게 만질만한 옵션이 없다 Role Name만 AWSLambdaBasicExecutionRole로 변경해주고 업로드한다.

업로드가 정상적으로 완료되면 업로드 윈도우가 자동으로 종료되고, AWS Explorer를 보면 AWS Lambda에 방금 추가한 Function이 추가되어있다.

Error : Could not find the required '{Assembly}.deps.json'

{
  "errorType": "LambdaException",
  "errorMessage": "Could not find the required 'AWSLambda_basic.deps.json'.
                  This file should be present at the root of the deployment package."
}

새롭게 생성된 Function 윈도우에서 샘플 테스트를 진행하는데 보고 따라했음에도 에러가 생긴다. 참 신기한 세상이다.

내 머리가 레전드인건지..

해당 오류는 *.deps.json 파일이 없어서 생기는 오류인데, *.deps.json 파일은 프로젝트를 publish하게 되면 .\bin\Debug\\{runtime}\publish\ 디렉터리에 생성되는 파일이다. AWS Lambda에 업로드하기 전에 Visual Studio에서 dotnet publish 후 파일 생성까지 확인.

해결

dotnet publish한 프로젝트를 다시 AWS Lambda에 업로드했지만 해당 오류는 해결되지 않았다. 이래저래 테스트를 하던 중 AWS Lambda 업로드 중 Rold Name을 기존 AWSLambdaBasicExecutionRole에서 AWSLambdaRole (Default policy for AWS Lambda Service Role.)으로 변경했고, AWS Lambda에 업로드된 ToUpper() 함수는 정상적으로 동작했다.

Ending

한동안 기록없이 코드만 치다보니 감이 떨어진듯하다. 습관이 이렇게 무섭다.

앞으로 기록할 것들

• AWS Lambda에 업로드한 코드 수정하기(json parsing)
• dotnet publish 패키지 증발 현상
• AWS Lambda 함수와 AWS API Gateway 연동하기
• AWS EC2 ubuntu에 Docker 환경 구축하기 + ASP.NET Core Docker Image

기록할 일이 많다는건 좋은 상황인지, 아닌지.

[참고] AWS Lambda에 C# Handler 만들기 - devstarsj

새로운 회사에 이직하게 되었다. 자체 서비스를 C#으로 운영하고 있기에 적응해야 한다. 아마 개인적으로 스터디하는 내용을 이 게시물에 계속 추가하지 않을까 싶다. 정확하지 않은 내용이 있다면 따로 표시해놓고 수정할 계획이다.

DataGrid

Grid는 컨트롤들을 담지만 DataGrid는 사용자 정의 가능한 표 형태로 데이터를 표시하는 컨트롤로 행/열에 데이터를 표시하는 유연한 방법을 제공

DataGridColumn에 추가할 수 있는 3가지 Column이다. 많이 사용하는 Text와 CheckBox Column은 따로 지원하지만, 나머지는 DataGridTemplateColumn을 사용해야 한다.

결론 : Text, CheckBox가 아닌 원하는 컨트롤을 넣고 싶을 때 DataGridTemplateColumn을 사용한다.

[참고] WPF DataGrid 예제 - 오라클자바커뮤니티(OJC.ASIA) // C# 관련된 포스팅이 꽤 있는편이다. 따로 시간내서 하나씩 보면 좋을듯

Question mark

Python, Javascript와는 다르게 변수 타입에 ?를 붙여 사용하는 경우가 많다.

public partical class ExampleModel
{
  private int? a = null; // OK
  private int b = null; // error since b is not nullable
}

위와 같이 C#에서 int?, bool?, DateTime?와 같은 T?의 표현은 .NET의 Nullable<T>와 같은 표현이다. Nullable<T> 구조체는 값을 가지고 있는지 체크한다. Nullable 타입과 연관되어 자주 사용되는 ?? 연산자는 ?? 앞의 파라미터가 NULL인 경우 연산자 뒤의 값을 할당한다.

double _Sum = 0;
DateTime _Time;
bool? _Selected;

public void CheckInput(int? i, double? d, DateTime? time, bool? selected)
{
    if (i.HasValue && d.HasValue)
        this._Sum = (double)i.Value + (double)d.Value;

    // time valid check
    if (!time.HasValue)
        throw new ArgumentException();
    else
        this._Time = time.Value;

    // if selected is NULL > false
    this._Selected = selected ?? false;
}

Nullable 타입이 필요한 이유 : SQL 서버 테이블에서 NULL을 허용하는 컬림이 있을 때, 테이블의 NULL 속성을 표현하기 위해서

Binding

Binding은 데이터 또는 속성(프로퍼티)을 서로 연결하여 동적으로 변환 및 참조할 수 있도록 한다. 한 엘리먼트의 속성을 다른 엘리먼트의 속성, 또는 데이터와 연결하는 과정 Binding을 통해 간단하게 서로 값들을 참조하여 동적으로 변경시킬 수 있고, 긴 처리 없이 간단하게 리스트에 DataTable을 표시하는 등 장점이 많기 때문에 WPF 작업시에 Binding은 필수적으로 사용된다.

Binding은 XAML측, Code-behind(C#)측에서 하는 방법이 존재한다.

XAML Binding

<!-- XAML Binding -->
<!-- Controll TextBox to ScrollBar -->
<ScrollBar Name="scrollBar" Orientation="Horizontal" Maximum="100" LargeChange="10"
    SmallChange="1" Value="{Binding ElementName=textbox, Path=Text, Mode=OneWay}"/>
<TextBox Name="textbox" VerticalAlignment="Top"/>

Code-behind Binding

int i = 0;
private void btn0_Click(object sender, RoutedEventArgs e)
{
    i++;
    Binding binding = new Binding();
    binding.Source = slider;   // Slider
    binding.Path = new PropertyPath("Value");   // Property of Slider
    if (i % 5 == 0) binding.Mode = BindingMode.Default;
    if (i % 5 == 1) binding.Mode = BindingMode.OneTime;
    if (i % 5 == 2) binding.Mode = BindingMode.OneWay;
    if (i % 5 == 3) binding.Mode = BindingMode.OneWayToSource;
    if (i % 5 == 4) binding.Mode = BindingMode.TwoWay;
    lbl.SetBinding(ContentProperty, binding);

    lblMode.Content = binding.Mode;
}

private void btn1_Click(object sender, RoutedEventArgs e)
{
    if(lbl.Content != null) lbl.Content = (double)lbl.Content + 1;
}

Binding Mode

[참고] Binding Mode Example (XAML)

[참고] Binding Mode Example (Code-behind)

Reference Site

CHashtag Blog

Got permission denied while trying to connect to the Docker daemon socket at ...

$ docker ps
Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get http://%2Fvar%2Frun%2Fdocker.sock/v1.40/containers/json: dial unix /var/run/docker.sock: connect: permission denied

$ docker ps 명령어를 입력했을때 마주치게 되는 권한 에러로 일반적으로 도커 소켓에 접근할 권한이 없기 때문에 발생한다. 이런 경우 docker ps 앞에 sudo를 붙여주면 해결이 되지만, 사용자 계정에서도 도커에 대한 접근이 가능하게 할 수 있도록 docker 그룹에 사용자를 추가한다.

$ sudo usermod -aG docker $USER_NAME
$ sudo su - $USER_NAME

위와 같이 적용하게 되면 sudo 명령어 없이도 정상적으로 docker 명령어를 사용할 수 있다.

    
    $ mkdir git-from-dockerfile
    $ cd git-from-dockerfile
    

작성중...

built-in function imwrite returned NULL without setting an error.

OpenCV를 이용하여 jpg to png 변환 Process 과정을 거칠 상황이 생겨 코드를 작성하던 중 마주친 에러

def jpg_to_png(path):
    filePath = '{}'.format(path)
    directory_name = basename(path)
    print('target directory :', filePath)
    fileExt = r'*.jpg'
    target_list = list(pathlib.Path(filePath).glob(fileExt))

    for target in range(0, len(target_list)):
        print('[INFO] target_list[{}] :'.format(target), target_list[target])
        target_file = target_list[target]
        img = cv2.imread(target_file)
        cv2.imwrite(r'{0}\{1}_{2}.png'.format(filePath, directory_name, target), img)
        print('[COMPLETE] {0} / {1} :'.format(target, len(target_list)))

argparse를 통해 변환 디렉토리에 대한 path를 인자로 받아 path 변수로 해당 경로를 전달하여 디렉토리 내에 jpg 파일을 png로 변환하는 코드이다.

img = cv2.imread(target_file)

해당 부분에서 OpenCV SystemError가 발생했고, 해당 오류 수정을 위해 인터프리터 환경으로 전환하여 오류 확인을 진행하였다. 일반적으로 파일의 경로는 str 타입으로 받아오는 경우가 많은데, 디렉토리 내에 jpg 파일 리스트를 가져오는 과정에서 사용한 pathlib 패키지에서 WindowsPath 타입으로 경로를 받아오는 현상이 발생했다.

의외로 타입 변환을 통해 간단하게 해결했다.

img = cv2.imread(str(target_file))

결론

쉽게 해결할 수 있는 문제는 차근차근 쉽게 생각해서 쉽게 해결해보자.

ubuntu 시스템에서 종종 사용하는 tmux인데, 자주 사용하는 유틸리티가 아니다보니 종종 사용법을 잊는 경우가 발생하여 벨로그에 남겨봐야겠다.

tmux install(ubuntu)

다른 시스템에선 사용해본적이 없어서 어떻게 설치하는지는 모르겠다. 아래는 Ubuntu 기준으로 작성됨.

$ apt-get install tmux

tmux command

tmux가 다 좋은데 커맨드가 머리에 잘 안남는다. 내가 멍청한 이유일지도 모르겠다. 아무튼 tmux의 커맨드는 ctrl+b가 기본이며, 이후 추가 입력키를 입력해서 사용하는 방식이다.

tmux Session

create session

$ tmux new -s [name]

kill session

$ tmux kill-session -t [name]

hide session

새롭게 생성한 세션에서 할 일을 마친 뒤 유지시키고 싶은 상태에서 기존 터미널로 나가고 싶은 경우

$ ctrl + b + d

visible session

hide session을 통해 벗어난 세션에 복귀하고 싶은 경우

$ tmux a -t [name]

tmux window

window는 탭 정도라고 생각하면 됨.

create window

$ ctrl + b + c

move window

$ ctrl + b + [window number]

panes

panes는 화면 분할(split)에 사용된다.

horizontal split

$ ctrl + b + %

vertical split

$ ctrl + b + "

panes move

panes간에 커서를 이동할 때 사용

$ ctrl + b + [arrow]

1. Text Gradient / Scroll list

2. pushNamedAndRemoveUntil

3. AlertDialog

4. AutomaticKeepAliveClientMixin

5. Flutter Youtube

헤비프랜 - Heavy Fran Youtube

Concurrency / Throughput

Node.js에서 JavaScript 실행이 싱글 스레드(이벤트 루프와 같은 스레드)에서 동작합니다. 따라서 Node.js의 동시성은 다른 작업이 완료된 후에 JavaScript 콜백 함수를 실행하는 이벤트 루프의 능력을 의미한다. JavaScript 실행은 하나의 이벤트 루프에서만 동작하지만 이벤트 루프의 여러 콜백 함수를 실행하여 동시에 처리되도록 보이는 것을 의미한다.

동시에 실행되어야 하는 모든 코드는 I/O 등의 JavaScript가 아닌 작업(이벤트 루프 스레드 외 다른 스레드)이 일어나는 동안 이벤트 루프가 계속 실행될 수 있도록 해야한다.

이벤트 루프는 동시 작업을 다루려고 부가적인 스레드를 만드는 다른 언어의 모델과는 다르다. (Node.js는 스레드를 따로 생성하지 않음) => (Node.js 10버전으로 들어오면서 Worker_thread라는 모듈을 통해 스레드 생성 가능하도록 변경됐다.)

Node.js System

libuv란 비동기 I/O에 집중하는 멀티 플랫폼 라이브러리이다. C언어로 개발되었으며 사실상 Node.js를 위해 개발된 것이다. 이 라이브러리는 다양한 I/O 폴링 메커니즘에 대한 단순한 추상화 이상의 기능을 제공한다. 어느 운영체제에서도 가능한 file I/O와 thread 기능 또한 제공된다.

libuv에는 thread pool이 존재하는데 이 thread pool에 있는 thread가 동기적인 입출력 작업을 이벤트 루프 대신 처리를 해준다. 또한 이 libuv를 통해 이벤트 루프를 제어한다.

Event Loop

이벤트 루프는 가능하다면 언제나 시스템 커널에 작업을 떠넘겨서 Node.js가 논블로킹 I/O 작업을 수행하도록 한다.

1. Library

기본적으로 Flutter 개발 중 아이콘 변경을 진행은 가능하지만 그 과정이 어느정도의 귀찮음을 동반하기 때문에 외부 라이브러리를 활용하여 간편하게 App Launcher Icon 변경하는 방법에 대해 작성해볼까 한다.

flutter_launcher_icons

flutter_launcher_icons : 기존에 다소 복잡했던 아이콘 변경의 과정을 커맨드 라인으로 간편하게 아이콘 변경이 가능한 라이브러리. 아이콘 롤백이 필요한 경우 이전 런처 아이콘을 유지할 수있는 옵션 존재. 작성일 기준 2020년 8월에 발표된 flutter_launcher_icons 0.8.1이 LTS 버전이다.

라이브러리 설치는 pubspec.yaml 하위에 있는 dev_dependencies에 아래와 같이 추가하면 된다.

dev_dependencies:
        ...
        ...
        ...
    flutter_launcher_icons: ^0.8.1

외부 라이브러리 설치에 대한 설명은 아래 링크 https://velog.io/@re_brother/TIL-Flutter-Study-2-December-23-2020 4. Client-Server Test using Node.js - Export Module 항목에 작성되어있다.

2. Configure

icon

아이콘은 1024px * 1024px, Alpha(투명) 값이 없어야 한다. 해당 아이콘을 ./assets/ 디렉터리에 추가하고, pubspec.yaml > assets에 path를 추가한다.

flutter_launcher_icons.yaml

pubspec.yaml과 동일한 디렉터리에 flutter_launcher_icons.yaml파일을 생성한 뒤 아래와 같이 작성한다.

flutter_icons:
  android: "launcher_icon"
  ios: true
  image_path: "assets/icon.png"

image_path는 실제 아이콘으로 사용할 이미지의 path를 입력한다.

3. Command run

터미널에 flutter pub run flutter_launcher_icons:main 입력 후 run 위와 같은 콘솔이 출력되었다면 정상적으로 아이콘이 변경된 것을 확인할 수 있다.

Gradle threw an error while downloading artifacts from the network

Flutter App 테스트를 진행하던 중 [!] Gradle threw an error while downloading artifacts from the network 에러가 발생했다. 딱히 작업 중에 다른 파일을 수정했던건 없었는데 무슨 이유인지 앱 빌드가 되지 않아 나중을 위해 해결 방법을 작성해놓을까 한다.

gradle-wrapper.jar

> .\flutter_app\android\gradle 위치에 있는 gradle-wrapper.jar파일 삭제

gradle-wrapper.properties

1. gradle-wrapper.jar와 동일 디렉터리에 있는 gradle-wrapper.properties 파일 Open

2. #Fri Jun 23 08:50:38 CEST 2017
   distributionBase=GRADLE_USER_HOME
   distributionPath=wrapper/dists
   zipStoreBase=GRADLE_USER_HOME
   zipStorePath=wrapper/dists
   distributionUrl=https://services.gradle.org/distributions/gradle-5.6.2-all.zip```
   
   

gradle-wrapper.properties 파일 하단에 존재하는 distributionUrl=https://.../gradle-5.6.2-all.zip을 https://.../gradle-6.4.1-all.zip으로 변경한 뒤에 터미널에 flutter run 입력 후 정상적으로 컴파일이 진행되는지 확인한다.

Another Solution

위 방법이 아닌 터미널창에 flutter build 명령어를 입력하면 해결된다는 글이 있는데, 해결 가능한 방법인지 아닌지는 확인을 하지 못했다. 아무튼 그런 방법도 있다고 한다.

1. Multiple FloatingActionButton 2. Image Move 3. Button Label 4. Client-Server Test using Node.js

1. Multiple FloatingActionButton

일반적인 Flutter개발 환경에서는 FloatingActionButton을 1개만 선언이 가능하다. 하지만 Stack 등을 이용하여 다중의 FloatingActionButton을 구현 가능하며, 테스트를 진행하던 도중 Scaffold 구조로 작성된 코드의 경우 정상적으로 구동이 불가능한 현상이 발생했다. 물론 FloatingActionButton Asset 외에도 RaisedButton, FlatButton, IconButton 등이 존재하지만 막연하게 "다중 FloatingActionButton을 만들 수 있는 방법은 없을까?" 라는 생각이 들었다.

What happened?

엄청난 일이 있었던건 아니다. 앞에 말했듯이 막연한 생각으로 FloatingActionButton을 하나 더 만들어보고 싶었고, Flutter에서는 FloatingActionButton은 더이상 선언이 불가능하다.

Try 1

물론 아예 방법이 없진 않았다. 아래와 같이 FloatingActionButton을 Stack으로 묶어 Align으로 나눈 다음 선언을 한다면 한 화면 내에 여러 개의 FloatingActionButton 생성이 가능하다.

Stack(
  children: <Widget>[
    Align(
      alignment: Alignment.bottomLeft,
      child: FloatingActionButton(...),
    ),
    Align(
      alignment: Alignment.bottomRight,
      child: FloatingActionButton(...),
    ),
  ],
)

Try 2

현재 코드는 Scaffold 구조로 구성되어 있어서, 아래와 같이 Stack 앞에 floatingActionButton을 선언한다.

floatingActionButton: Stack(
  children: <Widget>[
    Align(
      alignment: Alignment(Alignment.bottomRight.x, Alignment.bottomRight.y - 0.4),
      child: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: Icon(Icons.arrow_upward_sharp),
      ),
    ),
    Align(
      alignment: Alignment(Alignment.bottomRight.x, Alignment.bottomRight.y - 0.2),
      child: FloatingActionButton(
        onPressed: _decrementCounter,
        tooltip: 'Decrement',
        child: Icon(Icons.arrow_downward_sharp),
      ),
    ),
    Align(
      alignment: Alignment.bottomRight,
      child: FloatingActionButton(
        onPressed: _initCounter,
        tooltip: 'Initialize',
        child: Icon(Icons.album_outlined),
      )
    )
  ],
),

Result

Alignment의 y값을 받아 각 버튼의 위치를 0.2, 0.4씩 변경했다.

2. Image Move

Multiple FloatingActionButton에서 여러 개의 FloatingActionButton을 통해 counter 변수의 값을 증가/감소할 수 있는 기능을 구현했다. 해당 기능을 활용하여 import된 이미지의 위치를 조정하는 기능을 구현해보자.

    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Container(
              //Image.asset('assets/images/test_img.png'),
              color: Colors.blue,
              width: 200,
              height: 200,
            ),

            Text(
              'You have pushed the button this many times:',
            ),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headline2,
            ),
          ],
        ),
      ),

이미지를 삽입하기 전 body에 테스트용 Container를 추가하여 해당 영역 안에 이미지를 배치할 예정이다.

Import Image

현재 프로젝트 디렉터리 구조이다. 해당 프로젝트에서 사용되는 외부 이미지와 리소스들은 모두 pubspec.yaml에 path를 꼭 작성해야한다.

flutter:
  # The following line ensures that the Material Icons font is
  # included with your application, so that you can use the icons in
  # the material Icons class.
  uses-material-design: true
  assets:
    - assets/images/test_img.png
    ...

물론 1개의 파일만 추가한다면 해당 파일의 상대 경로(assets/images/test_img.png)를 추가하면 된다. 하지만 하나의 파일이 아닌 디렉터리 단위로 추가하게 될 경우 해당 디렉터리의 상대 경로(assets/images/)를 추가하면 된다. 이 때 상대 경로의 기준점은 pubspec.yaml이다.

이렇게 외부 이미지 경로에 대한 정의를 한 뒤에 main.dart 파일로 돌아와서 해당 이미지를 출력한다.

return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Container(
              color: Colors.blue,
              width: 200,
              height: 200,
            ),

            Image.asset('assets/images/test_img.png'),

            Text(
              'You have pushed the button this many times:',
            ),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headline2,
            ),
          ],
        ),
      ),

Image.asset()은 로컬에 위치한 이미지를 출력할때 사용되고 네트워크에 위치한 이미지를 Load 해야하는 경우에는 Image.network()를 사용한다.

Image Location

현재 테스트 프로젝트는 mainAxisAlignment로 각 material들의 y축이 상대적으로 고정되어있기 때문에 이미지를 Container에 배치한 상태로 이미지의 x-Alignment Value를 변경할 예정이다.

 return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Container(
              child: Image.asset('assets/images/test_img.png', width:200, height:200, fit: BoxFit.fill),
              padding: EdgeInsets.only(left: 2, right: 2, bottom: 1),
              alignment: Alignment(0 - (100 - _counter)/100, 0),
            ),

            // Image.asset('assets/images/test_img.png'),

            Text(
              'You have pushed the button this many times:',
            ),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headline2,
            ),
          ],
        ),
      ),

위와 같이 코드를 작성하였으며, 이미지 Container의 x좌표의 위치를 변경하기 위해 해당 컨테이너의 alignment를 Alignment(0 - (100 - _counter)/100, 0)로 선언하여 _counter의 값이 변경될 때 마다 이미지의 위치가 변경된다.

3. Button Label

Fluter Official Documents를 보다가 각 버튼에 label이 가능하다는 사실을 알게되었고 이 label 기능을 추가해볼까 한다. 위 이미지 처럼 기존에 정의해놓은 아이콘 우측으로 label을 추가하는 방식이다.

      // Origin Code
      floatingActionButton: Stack(
        children: <Widget>[
          Align(
            alignment: Alignment(Alignment.bottomRight.x, Alignment.bottomRight.y - 0.4),
            child: FloatingActionButton(
              onPressed: _incrementCounter,
              tooltip: 'Increment',
              child: Icon(Icons.arrow_upward_sharp),
              backgroundColor: Colors.indigo,
            ),
          ),

기존 FloatingActionButton에 바로 label속성을 추가하게 되면 child에 종속되어있는 Icon속성과 정상적으로 매칭되지 않아 아래와 같은 오류가 발생한다. 일반적인 버튼에 Label속성을 추가하기 위해서는 FloatingActionButton의 extended 메소드를 활용해야한다.

      floatingActionButton: Stack(
        children: <Widget>[
          Align(
            alignment: Alignment(Alignment.bottomRight.x, Alignment.bottomRight.y - 0.4),
            child: FloatingActionButton.extended(
              onPressed: _incrementCounter,
              tooltip: 'Increment',
              icon: Icon(Icons.arrow_upward_sharp),
              label: Text('Increment'),
              backgroundColor: Colors.indigo,
            ),
          ),

FloatingActionButton.extended 하위에 icon과 label을 새롭게 선언하여 조금 더 직관적인 UI를 만들 수 있다.

4. Client-Server Test using Node.js

간단하게 Flutter 앱 내에서 Node.js 서버와 통신을 진행해보려 한다. 일단 Node.js 서버는 요청에 대한 응답만 넘겨주는 정도로 간단하게 구현한다.

Server(Node.js)

const http = require("http");

let fs = require('fs');
let bodyParser = require('body-parser');
// DB Start
const sqlite3 = require('sqlite3').verbose();
let sql = `SELECT * FROM user`;

let db = new sqlite3.Database('./app/database.db', (err) => {
        if (err) {
                return console.error(err.message);
        }

        console.log('Connected to the in local SQLite database.');
        db.all(sql, [], (err, rows) => {
                if (err) {
                        throw err;
                }
                rows.forEach((row) => {
                        console.log(row);
                });
        });

});
// DB End

http.createServer((req, res) => {
        res.statusCode = 200;
        res.setHeader('Content-Type', 'text/plain');
        res.end('Node.js Server-Client Test');
}).listen(4004, () => {
        console.log("Server Running at localhost:4004");
});

간단하게 테스트용으로만 구현하려고 했는데, 마침 SQLite 테스트용 서버를 구축해놓은 코드가 있어서 해당 코드를 활용하여 테스트를 진행할 예정이다. 혹시나 DataBase가 필요없는 경우에는 주석 DB Start부터 DB End까지 삭제한 뒤에 진행하면 된다.

Export Module

물론 http 라이브러리가 기존에 설치되어 있다면 아무런 제약사항이 없겠지만 혹시나 http 모듈을 설치해야 한다면 pubspec.yaml -> dev_dependencies 하위에 해당 모듈의 이름과 버전을 선언하고, 커맨드창에서 flutter pub get 명령어를 입력하면 자동으로 설치된다.

Client(Flutter)

서버와 통신하기 위해서는 http 라이브러리가 필요하기 때문에 Flutter 코드 최상단에 http 라이브러리를 참조한다.

import 'package:http/http.dart';

Node.js Server - flutter Client 통신은 아래와 같이 진행하였으며, 이에 대한 내용은 주석으로 번호를 표시하여 설명하겠다.

  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  // Section 1
  String serverResponse = '';

  // Section 2
  _makeGetRequest() async {
    Response response = await get( _nodeCall() );
    setState(() {
      serverResponse = response.body;
    });
  }

  // Section 3
  String _nodeCall()
  {
      return 'http://10.110.31.211:4004';
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            // Section 4
            Text('Server Response\n', style: Theme.of(context).textTheme.headline5),
            Text('[ ' + serverResponse + ' ]', style: Theme.of(context).textTheme.headline6),
            Container(
              child: Image.asset('assets/images/test_img.png', width:200, height:200, fit: BoxFit.fill),
              padding: EdgeInsets.only(left: 2, right: 2, bottom: 1),
              alignment: Alignment(0 - (100 - _counter)/100, 0),
            ),

            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headline2,
            ),
          ],
        ),
      ),

      floatingActionButton: Stack(
        children: <Widget>[
          Align(
            alignment: Alignment.bottomRight,
            child: FloatingActionButton.extended(
              // Section 5
              onPressed: _makeGetRequest,
              tooltip: 'Initialize',
              icon: Icon(Icons.album_outlined),
              label: Text('  Node.js   '),
              backgroundColor: Colors.blue,
            )
          )
        ],
      ),
    );

Section 1 : String 형태의 serverResponse를 선언한다. 해당 변수는 최초 init시에 공백으로 보여지게 되며, 이는 Section 2에서 클라이언트 요청에 대한 서버의 response를 표시한다. Section 2 : async 방식으로 서버에 요청한다. Section 3에서 요청된 응답을 get하여 response에 저장한다. Section 3 : 지정해놓은 서버에 요청을 전달하여, 응답 내용을 return한다. Section 4 : 응답받은 serverResponse를 출력한다. Section 5 : FloatingActionButton에 _makeGetRequest Function을 적용한다.

5. Reference Pages

구글링을 통해 여러 문제들을 해결했지만, 정리해놓고 필요할 때 마다 참고하면 좋을 블로그들

▶ Flutter Widget 정리 Tistory ▶ Flutter Image Properties 정리 Tistory ▶ Markdown 문법 정리 Velog

What is Flutter?

Flutter 는 Google 에서 만든 Cross-Platform Framework 이다. 하나의 코드 Base 로 Android / iOS 심지어 Desktop App 까지 개발 할 수 있다. Dart로 작성된 하나의 코드는 각 OS에 맞게 Convert 과정을 거쳐 Build 된다.

Flutter Development Environment

Install list

1. Android Studio [Link]
2. Android Plug-in Android Studio 실행 후 [Files] -> [Settings] 또는 Ctrl + Alt + S 단축키를 이용하여 Plugins 탭에서 Flutter를 설치한다. Flutter Plugin을 설치하게 되면 Dart Plugin도 함께 설치된다.
3. Android Virtual-Machine [Tools] -> [AVD Manager] 또는 우측 상단 아이콘을 클릭하여 AVD Manager를 실행한다.

Create Virtual Device 버튼을 클릭해서 새로운 안드로이드 가상 머신을 생성한다. Android 버전은 자유롭게 선택해도 되지만, 호환 및 테스팅 이슈가 존재할 수 있으므로 Android 10 또는 11을 사용하기를 추천한다.

4. Flutter SDK [Link] Flutter SDK를 다운받아 압축 해제 후 flutter 폴더 전체를 C드라이브 최상위 디렉터리로 이동한다.

정상적으로 폴더를 이동했다면 C:\flutter\에는 위와 같은 structure를 가진다. 이후 SystemPropertiesAdvanced를 실행하여 C:\flutter\bin\ 경로를 환경변수 PATH에 추가한다. 환경변수 추가까지 정상적으로 진행했다면 명령 프롬프트(cmd)에 flutter doctor를 실행해본다.

최초 실행 시에는 위와 같은 화면이 출력된다.

이어서 위와 유사한 커맨드가 나오게 되는데, 아마 Android toolchain 부분에 WARNING이 존재한다. 안드로이드 라이센스 관련된 내용인데 해당 부분에 대한 해결을 위해 커맨드에 flutter doctor --android-licenses를 입력하고, accepted (y/N)? 에서 전부 y를 해주면 된다.

여기까지 진행이 완료되었다면 Android Studio, VS Code, Connected device 총 3개의 warning이 존재하는데 Android Studio Warning은 실제 개발 환경에 추가 Plugin을 설치했기 때문에 패스해도 된다고 한다. VS Code는 개발 환경에 추가하지 않을 예정이기 때문에 패스할 것이고, Connected device는 현 시점에서 Virtual-Machine이 동작하지 않고 있기 때문에 발생하는 오류이다.

TIP?..

혹시나 커맨드창에 flutter doctor 명령어가 정상적으로 실행되지 않고 'flutter'는 내/외부 명령, 실행 프로그램, 배치 파일이 아니라고 뜨는 경우에는 환경 변수가 정상적으로 등록되지 않은 경우이므로, 커맨드창에 set 명령어를 입력하여 환경변수를 시스템에 적용하면 된다.

Create Android Studio Flutter Project

Android Studio 실행 시 관리자 권한으로 실행해주세요.

Android Studio를 관리자 권한으로 실행 후 [File] -> [New] -> [New Flutter Project]를 눌러서 새 플러터 프로젝트를 생성합니다.

템플릿의 경우 Flutter Application을 선택하고, 다음 페이지로 넘어갑니다.

Project Name, Description은 자유롭게 작성하고 Flutter SDK path에 아까 다운로드받은 Flutter SDK의 절대경로를 입력한다. 제대로 안적으면 다음으로 넘어갈 수 없으니 꼭 유의해서 작성하도록 한다.

Android 개발만 진행한다면 Include Kotlin support for Android code만 체크하면 되고, 반대로 iOS 개발만 진행한다면 Include Swift support for iOS code만 체크하면 된다. 굳이 하나의 플랫폼만 개발할 이유는 없으므로 양쪽 다 체크하고 프로젝트 생성을 마친다.

프로젝트 생성이 완료되면 새로운 Android Studio가 열리고, 좌측에 아래와 같은 파일 및 폴더들이 생성된 것을 확인할 수 있다.

해당 폴더와 파일이 무엇을 의미하는지 간략하게 설명하고 마무리할까 한다.

android – Android Application을 만들기 위해 자동으로 생성된 소스코드 ios – iOS Application을 만들기 위해 자동으로 생성된 소스코드 lib – Flutter Framework를 사용하여 쓰여진 다트 코드를 담고 있는 메인 폴더 lib/main.dart – Flutter Application의 엔트리 포인트 test – Flutter Application을 테스트하기 위한 Dart 코드를 담고 있는 폴더 test/widget_test.dart – Sample Code .gitignore – Git에 들어가지 않을 파일들 설정 .metadata – Flutter 툴에 의해 자동 생성됨 .packages – Flutter 패키지를 추적하기 위해 자동 생성됨 .iml – Android Studio에 의해 사용되는 프로젝트 파일 pubspec.yaml – Pub에 의해 사용되는 Flutter Package Manager