macOS에서 ServBay로 ASP.NET Framework 4.x 개발하기
ServBay는 강력한 Mono 환경을 기본 내장하여, macOS에서도 ASP.NET Framework 1.1/2.0/3.x/4.x(최대 4.7.x까지 지원) 개발 및 테스트를 쉽고 간편하게 할 수 있도록 지원합니다.
ServBay v1.12.0 버전부터 Mono 6.14.0을 통합했고, XSP 개발 서버와 fastcgi-mono-server 도구도 함께 제공되어 ASP.NET Framework 4.x 애플리케이션을 실행하는 두 가지 주요 방식을 사용할 수 있습니다.
- XSP를 이용한 빠른 개발 및 테스트: XSP는 Mono 환경에 최적화된 경량형 ASP.NET 웹 서버로, 개발 및 빠른 테스트 단계에 적합합니다.
- Nginx + FastCGI 배포: 이 방식은 더 안정적이며 성능도 우수하고, 실서비스 환경과 유사하게 Nginx가 요청을 Mono 백엔드 프로세스로 전달해 처리합니다.
이 문서는 ServBay 환경에서 ASP.NET Framework 4.x 프로젝트를 설정하고 실행하는 방법을 안내합니다.
.NET Framework와 .NET에 대하여
이 안내서는 Mono 기반 ASP.NET Framework 4.x 개발에 관한 내용으로, 과거 .NET 기술 스택을 다룹니다.
ServBay는 최신 .NET(.NET Core, .NET 5/6/7/8+ 포함) 개발 및 배포도 완벽하게 지원합니다. 신규 .NET 프로젝트를 개발하거나 최신 .NET 버전으로 이전하려는 경우, 본 문서의 Mono 방식을 사용하기보다는 ServBay가 제공하는 공식 마이크로소프트 .NET SDK/런타임 환경을 활용하실 것을 권장합니다.
사전 준비
- ServBay 설치: macOS에 ServBay v1.12.0 이상이 설치되어 있어야 합니다.
- Mono 설치:
- ServBay 앱을 실행하세요.
- 좌측 네비게이션 바에서 ‘패키지’를 선택합니다.
- 패키지 목록에서 「.NET」 카테고리를 찾아 확장합니다.
- 「Mono 6」(버전 6.14.0 이상)을 찾아 우측의 ‘설치’ 버튼을 클릭하고 설치가 완료될 때까지 기다립니다.
ASP.NET 프로젝트 준비
- 프로젝트 파일: ASP.NET Framework 4.x 웹 애플리케이션 또는 웹사이트 프로젝트와
web.config파일을 준비하세요. - 권장 저장 위치: 웹사이트 프로젝트는 ServBay가 관리하는
www디렉터리(/Applications/ServBay/www/)에 저장하는 것을 강력 추천합니다. 각 프로젝트 별로 하위 폴더를 생성하세요.- 예시: 프로젝트명이
MyWebApp라면, 권장하는 사이트 루트 경로는/Applications/ServBay/www/MyWebApp입니다. - 이후 단계에서
/Applications/ServBay/www/MyWebApp경로를 예시로 사용합니다. 실제 프로젝트 경로로 대체해 사용하세요.
- 예시: 프로젝트명이
방법 1: XSP(내장 개발 서버) 사용
XSP는 Mono 프로젝트에서 제공하는 경량형 웹 서버로, 로컬 개발 및 빠른 테스트에 특히 적합합니다. ServBay의 Mono 6 패키지에는 ASP.NET 4.x용 XSP4도 포함되어 있습니다.
안내
- ASP.NET 1.1 프로젝트는
xsp명령어를 사용하세요. - ASP.NET 2.0/3.x 프로젝트는
xsp2명령어를 사용하세요. - ASP.NET 4.x 프로젝트는
xsp4명령어를 사용하세요.
순서:
터미널 열기: macOS의 터미널(Terminal)을 실행합니다.
프로젝트 디렉터리로 이동:
cd명령으로 ASP.NET 프로젝트의 루트(즉,web.config가 있는 폴더)로 이동합니다.bash# 예시: MyWebApp 프로젝트 폴더로 이동 cd /Applications/ServBay/www/MyWebAppXSP 서버 실행: 프로젝트 루트에서 아래와 같이 XSP4 서버를 실행하세요. 다른 서비스와 충돌을 피하기 위해 사용하지 않는 포트(예: 8080 또는 9000)를 지정할 수 있습니다.
bash# 9000번 포트에서 현재 디렉터리의 프로젝트 실행 xsp4 --port 9000xsp4: .NET Framework 4.x에 맞는 XSP 서버를 실행합니다.--port 9000: 서버가 청취할 TCP 포트 번호를 지정합니다.
애플리케이션 접속: 브라우저를 열고
http://localhost:9000또는http://127.0.0.1:9000에 접속하면 ASP.NET 애플리케이션이 실행 중인 것을 확인할 수 있습니다.서버 중지: 개발이나 테스트가 끝나면 XSP를 실행했던 터미널 창으로 돌아가
Ctrl + C또는엔터키를 눌러 서버를 종료합니다.
장점:
- 설정이 매우 간단하고, 즉시 실행/테스트 가능
- 로컬 개발/디버깅에 매우 적합
단점:
- Nginx 같은 실서비스용 웹 서버보다 성능이 다소 낮음
- 기능이 기본적이라 실제 운영환경과 완전히 동일하지 않음
- 터미널 창을 항상 켜둬야 함
방법 2: Nginx + FastCGI 사용
이 방식은 ServBay가 관리하는 Nginx를 프론트엔드 웹 서버로 활용하여, 클라이언트 요청 처리 및 정적 파일 제공을 담당하고, FastCGI 프로토콜을 통해 동적 요청(예: .aspx, .ashx 등)은 Mono 백엔드 프로세스(fastcgi-mono-server4)에 전달합니다. 운영환경과 유사하게 배포할 수 있고, 성능도 우수하며 Nginx의 고급 기능(SSL, 캐시, 압축 등)도 활용할 수 있습니다.
안내
- ASP.NET 1.1 프로젝트는
fastcgi-mono-server명령어를 사용하세요. - ASP.NET 2.0/3.x 프로젝트는
fastcgi-mono-server2명령어를 사용하세요. - ASP.NET 4.x 프로젝트는
fastcgi-mono-server4명령어를 사용하세요.
순서:
Mono 및 Nginx 실행 확인:
- ServBay 패키지에서 Mono 6와 Nginx를 설치하세요.
- ServBay 서비스 메뉴에서 Nginx가 실행 중인지 확인합니다.
ASP.NET 프로젝트 준비: 프로젝트가
/Applications/ServBay/www/MyWebApp같은 권장 경로에 있는지 확인합니다.FastCGI Mono Server 실행:
- 새로운 터미널 창을 엽니다.
- 아래와 같이
fastcgi-mono-server4프로세스를 실행하세요. 이 프로세스가 Nginx의 FastCGI 요청을 수신하고 ASP.NET 페이지를 해석해 처리합니다.bash# 예시: MyWebApp 프로젝트에 대해 FastCGI 서비스 실행 fastcgi-mono-server4 --applications=/:/Applications/ServBay/www/MyWebApp \ --socket=tcp:127.0.0.1:9001 \ --loglevels=Standard \ --printlogfastcgi-mono-server4: .NET Framework 4.x용 FastCGI 서버 실행--applications=/:/Applications/ServBay/www/MyWebApp: URL 경로와 실제 파일 경로 매핑 지정./:는 사이트 루트(/),/Applications/ServBay/www/MyWebApp는 실제 프로젝트 경로입니다. Nginx가/some/page.aspx로 요청 시 Mono가/Applications/ServBay/www/MyWebApp/some/page.aspx에서 파일을 찾고 실행합니다. 본인의 프로젝트 경로로 반드시 변경하세요.--socket=tcp:127.0.0.1:9001: FastCGI 서버가 청취할 TCP 주소/포트(여기서는 127.0.0.1:9001). 이 포트가 ServBay 혹은 다른 앱과 중복되지 않아야 하며, 아래 Nginx 설정의fastcgi_pass와 동일해야 합니다.--loglevels=Standard --printlog: (선택사항) 터미널에서 표준 로그를 출력해 디버깅에 활용할 수 있습니다.
- 주의:
fastcgi-mono-server4가 실행 중인 터미널 창을 닫으면 서비스가 중단됩니다. 장시간 백그라운드 실행을 원할 땐nohup,screen,tmux등을 사용하는 것이 좋습니다.
Nginx 사이트 설정:
ServBay에서 ‘사이트’ 메뉴로 이동하세요.
‘사이트 추가’ 또는 기존 사이트 편집을 클릭하세요.
도메인명 설정: 예를 들어
mywebapp.servbay.demo처럼 브랜드와 관련된 도메인을 등록할 수 있습니다. ServBay가 자동으로 macOS Hosts 파일에 등록해 127.0.0.1로 연결해 줍니다.웹사이트 루트 디렉터리 설정: 매우 중요! 프로젝트 실제 경로(예
/Applications/ServBay/www/MyWebApp)로 지정해야 합니다. Nginx의root지시어에 반영되어 정적 파일 경로가 올바르게 매치됩니다.사용자 정의 설정 활성화: 사이트 설정 우측 상단의 ‘커스텀 설정’ 체크박스를 선택하세요. ServBay가 기본 Nginx 설정 파일을 자동 생성해줍니다. 이후 아래 예시처럼 추가/수정이 필요한 부분을 확인하여 ASP.NET 동적 요청을 FastCGI Mono Server로 연결하세요.
ServBay가 자동 생성한 설정을 바탕으로 주요 수정/추가가 필요한 예시:
nginxserver { listen 80; # HTTP 포트 리스닝 listen 443 ssl http2; # HTTPS 포트, SSL 및 HTTP/2 활성화 # ServBay가 자동 관리하는 SSL 인증서 설정 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384'; ssl_prefer_server_ciphers on; ssl_session_timeout 1d; ssl_session_cache shared:ServBay:10m; ssl_session_tickets off; # 인증서 파일 경로(도메인별로 자동 관리) ssl_certificate /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.crt; ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.key; server_name mywebapp.servbay.demo; # ServBay에 설정한 도메인과 일치해야 함 root /Applications/ServBay/www/MyWebApp; # **사용중인 웹사이트 루트와 반드시 동일** # ASP.NET 기본 문서 추가(Nginx에서 index.html/htm이 없으면 이를 시도) index index.html index.htm default.aspx Default.aspx; # 요청 처리의 핵심 로직 location / { # 파일($uri) 또는 디렉터리($uri/)를 순서대로 탐색 # 정적 파일이 없으면 @mono로 전달 try_files $uri $uri/ @mono; } # (선택/권장) Nginx가 주요 정적 파일을 효율적으로 처리 # expires로 브라우저 캐시 극대화 가능 location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ { expires max; log_not_found off; access_log off; } # 동적 요청 처리를 위한 @mono location 블록 정의 location @mono { # FastCGI를 통해 Mono 서버로 요청 전달 # **포트가 fastcgi-mono-server4 실행 시 --socket과 반드시 일치** fastcgi_pass 127.0.0.1:9001; # 표준 FastCGI 파라미터 포함 include fastcgi_params; # 핵심 파라미터: 실행 대상 ASP.NET 파일 경로 전달 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; # PATH_INFO는 보통 필요 없음, 빈 값으로 세팅 fastcgi_param PATH_INFO ""; # (선택) 추가 FastCGI 파라미터(HOST 등) 필요시 추가 가능 # fastcgi_param HOST $host; } # ServBay에서 추가로 로그 경로나 기본 설정이 붙을 수 있음 # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log; # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log; }설정 저장 및 Nginx 재시작: Nginx 설정을 저장하면 ServBay가 자동으로 구문 체크 후 재적용합니다. 에러 발생 시 경고 창이 표시되며, 필요시 ‘서비스’ 메뉴에서 Nginx를 수동으로 재시작할 수도 있습니다.
애플리케이션 접속: 웹 브라우저로 위에서 설정한 도메인(예:
https://mywebapp.servbay.demo)에 접속해 보세요. Nginx가 정적 파일은 직접 반환하고, 동적 요청은fastcgi-mono-server4로 전달하여 Mono가 ASP.NET 코드를 실행하게 됩니다.
장점:
- 성능이 우수하고 안정적이어서 실서비스 환경과 유사한 테스트 가능
- Nginx의 다양한 강력한 기능(정적 파일, SSL, 로드밸런싱 등) 활용 가능
- ServBay 사이트/도메인/Hosts 관리와 통합 운용 용이
단점:
- XSP보다 설정이 다소 복잡
fastcgi-mono-server4프로세스를 별도로 관리해야 함(백그라운드 실행 권장)
어떤 방식을 선택할까?
- 신속한 개발/디버깅/기능 테스트에는 XSP 방식이 가장 쉽고 빠릅니다. 단일 명령어로 바로 실행할 수 있습니다.
- 높은 성능, 실서비스 환경과 유사한 테스트 또는 Nginx 고급 기능(HTTPS, 커스텀 도메인, 정적 파일 최적화 등)과 ServBay의 사이트 관리 기능을 활용하려면 Nginx + FastCGI 방식을 권장합니다.
유의사항 및 문제 해결
- 파일 권한: Nginx(ServBay가 관리)와
fastcgi-mono-server4를 실행하는 macOS 사용자 모두 프로젝트 폴더(/Applications/ServBay/www/YourProjectName) 내 파일들에 충분한 읽기 권한이 있어야 합니다. 필요시chmod/chown명령어로 권한을 조정하세요. - 경로 일관성: Nginx 설정(
root)과fastcgi-mono-server4명령(--applications)에 지정한 프로젝트 경로가 정확히 일치해야 하며,web.config가 포함된 루트 디렉터리를 가리키는지 꼭 확인하세요. - 포트 충돌: XSP 및
fastcgi-mono-server4에서 사용하는 포트(예 9000, 9001)가 ServBay나 시스템의 다른 프로세스와 중복되지 않아야 합니다. - 로그 확인:
fastcgi-mono-server4실행 시 터미널에 표시되는 로그를 확인하세요.--printlog가 있으면 실시간 로그를 볼 수 있습니다.- Nginx 에러 로그도 확인하세요. ServBay 사이트 설정에서 해당 경로(
/Applications/ServBay/logs/nginx/your-domain.error.log)를 볼 수 있습니다. 에러 로그는 Nginx 설정이나 Mono FastCGI 통신 문제를 파악하는 데 중요합니다.
- Mono 버전 호환성: ServBay에 내장된 Mono 6.14.0은 .NET Framework 1.1~4.7.2 대부분의 기능을 지원합니다. 더 최신 기능이나 호환성 문제가 있다면 ServBay의 공식 마이크로소프트 .NET SDK/런타임 설치 또는 프레임워크 버전 다운그레이드를 고려하세요.
- FastCGI 프로세스 관리: Nginx + FastCGI 방식을 쓸 때
fastcgi-mono-server4는 계속 동작해야 하니 터미널을 켜두거나, 프로덕션에선 백그라운드 서비스나 프로세스 매니저를 이용해 관리하세요.
ServBay가 내장한 Mono 6 환경과 표준화된 프로젝트 구조를 활용하면, macOS에서도 전통적인 ASP.NET Framework 4.x 애플리케이션을 쉽고 체계적으로 개발‧실행할 수 있습니다. 본 문서가 여러분의 원활한 개발 시작에 도움이 되길 바랍니다!