App Builder 온프레미스 필수 요구 사항, 설치 및 구성 가이드

필수 요구 사항

이 섹션에서는 App Builder 온프레미스 버전을 설치하기 위한 필수 요구 사항을 나열하며, Linux/Mac OS/Windows를 유지 관리하고 지원하는 운영 매개변수를 구성하는 시스템 관리자를 대상으로 합니다.

데이터베이스 관리

요구 사항에 따라 MySQL, MSSQL Server 또는 PostgreSQL 데이터베이스 관리 시스템을 사용하도록 선택할 수 있습니다.

MySQL 설치

1 - MySQL 커뮤니티 에디션 (Windows용 직접 링크)을 설치합니다.

• 선택:

  • 개발자 기본값, 다음 및 실행.

  참고: "하나 이상의 제품 요구 사항이 충족되지 않았습니다. 계속하시겠습니까?"라는 메시지가 표시되면 예를 선택하기만 하면 됩니다)

• 설치가 완료된 후:

  • 다음을 선택하여 서버를 구성하고, 메시지가 표시되면 원하는 루트 암호를 입력한 다음 실행을 선택합니다.
  • 서버 구성이 완료된 후, 나머지 구성이 필요하지 않으므로 취소를 선택하여 설치 프로그램을 종료합니다.

2 - 컨테이너의 MySQL 연결을 허용합니다.

1단계의 루트 사용자 및 암호로 MySQL에 연결하고 다음 SQL 스크립트를 실행합니다(사용자 이름과 암호는 AppBuilder에서 사용할 것입니다).

참고: MySQL Workbench 도구를 사용하여 SQL 스크립트를 실행할 수 있습니다.

CREATE USER 'username'@'%' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON *.* TO 'username'@'%' WITH GRANT OPTION;

MSSQL Server 설치

1 - Sql Server (직접 링크)를 설치합니다.

온프레미스 Sql Express 설치

참고: 온프레미스 서버에는 VS의 임베드 Sql Server Express가 아닌 실제 Sql Server가 있어야 합니다.

2 - tcp/ip 활성화 - 자세한 설명은 여기를 참조하세요.

SqlServer 구성 관리자

3 - Sql Express의 일부인 새로운 App_Builder 사용자를 추가합니다. 이 목적을 위해 Sql Server Management Studio를 설치할 수 있습니다.

로그인 매개변수 대화

참고: 새로 추가된 사용자에 대해 데이터베이스 생성 권한이 거부될 수 있습니다. dbcreator와 같이 데이터베이스를 만들 수 있는 자격 증명을 제공할 서버 역할을 제공하는 것을 고려해야 합니다.

참고: 관리자 결정에 따라 SSMS와의 인증 모드 변경이 필요할 수 있습니다. SQL Server Database Engine은 Windows 인증 모드 또는 SQL Server 및 Windows 인증 모드로 설정됩니다.

Docker 설치

Windows 가이드 -> docs.microsoft.com 가이드

설치

이 섹션에서는 이미 Docker와 데이터베이스(MySQL, MSSQL Server 또는 PostgreSQL)가 설치되어 있다고 가정합니다.

처음 설치

1 - Infragistics 고객 포털의 다운로드 섹션에 포함된 appbuilder.zip을 다운로드합니다.
2 - appbuilder.zip 파일에 포함된 appbuilder.tar을 추출합니다.
3 - 추출된 위치에서 터미널 또는 명령 프롬프트 창을 엽니다.
4 - 이미지를 로드하고 확인합니다.

실행:

docker load --input appbuilder.tar

_image_가 올바르게 로드되었는지 확인하려면 아래 표의 예를 참조하세요:

docker images

REPOSITORY	TAG	IMAGE ID	CREATED	SIZE
appbuilder	1.0	2a05977e039b	12 days ago	854MB

5 - 컨테이너를 실행합니다:

docker run --restart always -p 80:5000 -e "ConnectionStrings:AppBuilderMySqlConnection=server=<your-mysql-database-ip>;database=<your-mysql-schema>;user=<your-mysql-database-user>;password=<your-mysql-database-password>;oldguids=false" -v <external-folder-for-logs>:/appbuilder/logs -v <external-folder-for-storage>:/appbuilder/storage --name appbuilder appbuilder:1.0

• MySQL 예제 - 이것은 MySql 인스턴스가 192.168.2.5에서 IndigoAppBuilderOnPrem이라는 스키마를 실행 중이고, 사용자 이름=appbuilder 및 암호=appbuilder이며 C:/AppBuilder를 로그 및 스토리지를 저장할 외부 폴더로 선택했다고 가정하는 명령입니다.

docker run --restart always -p 80:5000 -e "ConnectionStrings:AppBuilderMySqlConnection=server=192.168.2.5;database=IndigoAppBuilderOnPrem;user=appbuilder;password=appbuilder;oldguids=false" -v C:/AppBuilder/logs:/appbuilder/logs -v C:/AppBuilder/storage:/appbuilder/storage --name appbuilder appbuilder:1.0

• MSSQL Server 예제 - 이것은 Sql Server 인스턴스가 SQLEXPRESS 서버로 IndigoAppBuilderOnPrem이라는 스키마를 실행 중이고, USER ID=APP_BUILDER 및 암호=Appbuilder2023!이며 C:/AppBuilder를 로그 및 스토리지를 저장할 외부 폴더로 선택했다고 가정하는 명령입니다.

docker run --restart always -p 80:5000 -e "ConnectionStrings:Provider=SqlServer" -e "ConnectionStrings:AppBuilderSqlServerConnection=Data Source=DEV-ZKOLEV\SQLEXPRESS,1433;Database=IndigoAppBuilderOnPrem;User ID=APP_BUILDER;Password=Appbuilder2023!;Connect Timeout=15;Encrypt=False;TrustServerCertificate=False;ApplicationIntent=ReadWrite;MultiSubnetFailover=False" -v C:/AppBuilder/logs:/appbuilder/logs -v C:/AppBuilder/storage:/appbuilder/storage --name appbuilder appbuilder:1.0

6 - 브라우저를 열고 http://localhost/를 입력합니다.

참고: Docker Desktop을 사용하는 경우 컨테이너/앱으로 이동하여 컨테이너를 찾은 다음 브라우저에서 열기를 클릭합니다.

Docker 컨테이너/앱

OpenID Connect를 사용한 인증(OAuth 2.0)

자세한 정보는 OpenID Connect를 사용한 온프레미스 인증(OAuth 2.0) 항목을 따르세요.

업데이트

1 - 새로 발행된 zip 파일로 첫 설치의 첫 4단계를 따릅니다.

2 - 새 이미지가 올바르게 로드되었는지 확인합니다(이전 이미지에는 이라는 태그가 지정되어야 함).

docker images

REPOSITORY	TAG	IMAGE ID	CREATED	SIZE
appbuilder	1.0	27ff4c1079ac	43 hours ago	932MB
		2a05977e039b	12 days ago	854MB

3 - 컨테이너를 중지합니다.

docker stop appbuilder

4 - 컨테이너를 제거합니다.

docker rm appbuilder

5 - 첫 설치의 5단계에서 사용한 것과 동일한 명령으로 컨테이너를 실행합니다.

정품 인증

이 섹션에서는 이미 온프레미스 인스턴스를 설치했고 현재 실행 중이라고 가정합니다.

서버가 처음 시작될 때, 프롬프트 대화 상자에서 _설치 ID_를 제공하고 _인증 키_가 요청됩니다. 이 _설치 ID_를 지역별 영업 부서로 보내면 서버를 활성화할 _인증 키_를 제공합니다.

App Builder 활성화

참고: 키가 만료되기 30일 전에 UI를 통해 경고 메시지가 직접 표시됩니다.

구성 개요

기본 구성

사용자 정의 구성 없이 AppBuilder Docker 이미지를 시작하면 다음 기능이 기본적으로 사용 불가능합니다:

• 데이터베이스 연결 - 데이터베이스 자격 증명이 제공되지 않음(환경 변수 또는 구성 파일을 통해 구성해야 함)
• AI 기능 - 모든 AI 기능 사용 불가능
• AI 채팅 패널 - 채팅 인터페이스 숨김
• Teams 알림 - 외부 로깅 통합 없음
• 속도 제한 - 요청 제한 없음
• GitHub/Azure DevOps 통합 - 게시 기능 사용 불가능

구성 방법

AppBuilder를 구성하는 두 가지 옵션이 있습니다:

옵션 1: 환경 변수(빠른 시작)

컨테이너를 시작할 때 구성을 환경 변수로 직접 전달합니다:

docker run --restart always -p 80:5000 \
  -v C:/appbuilder/config:/appbuilder/config \
  -v C:/appbuilder/logs:/appbuilder/logs \
  -v C:/appbuilder/storage:/appbuilder/storage \
  --name appbuilder \
  appbuilder:1.0

필수 디렉터리 구조:

/appbuilder/config/
├── appsettings.json                    # 기본 구성 재정의
└── ai/                                 # AI 구성(선택 사항)
    ├── ai.appsettings.json             # AI 공급자 및 모델 설정
    ├── ai.providers.appsettings.json   # 공급자 엔드포인트 구성
    └── ai.credentials.appsettings.json # API 키 및 자격 증명
    └── ai.models.appsettings.json      # 사용 가능한 API 모델

구성 파일 참조

파일	목적	필수
appsettings.json	기본 백엔드 구성 - 데이터베이스, 인증, 로깅, 스토리지 및 통합을 제어
configs/ai/ai.appsettings.json	AI 기능 설정 - 사용할 AI 공급자 및 모델 정의	AI를 활성화한 경우에만
configs/ai/ai.credentials.appsettings.json	AI 공급자 API 키 - AI 서비스의 인증 자격 증명 저장	AI를 활성화한 경우에만
configs/ai/ai.providers.appsettings.json	AI 공급자 엔드포인트 - API 기본 URL 구성(변경이 거의 필요하지 않음)	AI를 활성화한 경우에만
configs/ai/ai.models.appsettings.json	AI 공급자 모델	AI를 활성화한 경우에만

참고: AI 기능을 활성화할 계획이 없으면 AI 구성 파일을 완전히 건너뛸 수 있습니다.

기본 구성(appsettings.json)

데이터베이스 연결

데이터베이스 연결 설정은 AppBuilder가 사용자 프로젝트, 구성 요소, 자산 및 메타데이터를 포함한 모든 애플리케이션 데이터를 저장할 위치를 결정합니다.

{
  "ConnectionStrings": {
    "Provider": "MySql",
    "AppBuilderMySqlConnection": "server=host.docker.internal;port=3306;database=IndigoAppBuilder;user=root;password=yourpassword;oldguids=false",
    "AppBuilderSqlServerConnection": "Data Source=<server>;Database=<database>;User Id=<username>;Password=<password>;Encrypt=False;TrustServerCertificate=True;MultipleActiveResultSets=True",
    "AppBuilderPostgreSqlConnection": "Host=<hostname>;Port=5432;Database=<database>;Username=<username>;Password=<password>"
  }
}

옵션	유형	설명
Provider	문자열	사용할 데이터베이스 엔진을 결정합니다. 유효한 값: "MySql", "SqlServer", "PostgreSql". 애플리케이션은 이 공급자 값과 일치하는 연결 문자열만 사용합니다.
AppBuilderMySqlConnection	문자열	MySQL/MariaDB 연결 문자열. Provider가 "MySql"일 때 사용됩니다. oldguids=false 매개변수는 적절한 GUID 처리에 필요합니다. host.docker.internal을 사용하여 Docker 호스트 머신의 데이터베이스에 연결하거나, server=mysql을 사용하여 Docker 컨테이너에서 호스팅되는 데이터베이스에 연결합니다. 중요: 컨테이너화된 데이터베이스를 사용할 때는 AppBuilder 컨테이너를 --network 옵션으로 시작합니다(예: docker run --restart always -p 8080:5000 --network appbuilder-network).
AppBuilderSqlServerConnection	문자열	SQL Server 연결 문자열. Provider가 "SqlServer"일 때 사용됩니다. MultipleActiveResultSets=True는 Entity Framework Core가 SQL Server와 제대로 작동하는 데 필요합니다.
AppBuilderPostgreSqlConnection	문자열	PostgreSQL 연결 문자열. Provider가 "PostgreSql"일 때 사용됩니다. 표준 Npgsql 연결 문자열 형식.

로깅 구성

애플리케이션 로그가 작성되고 관리되는 방식을 제어합니다.

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Warning",
      "Microsoft": "Warning"
    }
  },
  "CustomLogging": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning",
        "Microsoft.EntityFrameworkCore": "Error"
      }
    },
    "Files": {
      "Paths": {
        "AI": "./logs/ai.log",
        "Backend": "./logs/backend.log",
        "DataProtection": "./logs/data-protection.log"
      },
      "RollingInterval": "Infinite",
      "FileSizeLimitBytes": 52428800,
      "RollOnFileSizeLimit": true,
      "FlushToDiskInterval": "00:00:01",
      "Retention": 90
    },
    "Teams": {
      "AIError": {
        "Enabled": false,
        "LogicAppUrl": "",
        "Period": "00:00:01",
        "TeamId": "",
        "ChannelId": ""
      },
      "DataProtection": {
        "Enabled": false,
        "Email": ""
      }
    }
  }
}

Teams 알림

옵션	설명
Teams.AIError.Enabled	true일 때, AI 오류가 Logic App 웹훅을 통해 Microsoft Teams 채널로 전송됩니다.
Teams.AIError.LogicAppUrl	Teams에 게시하는 Azure Logic App의 URL입니다.
Teams.DataProtection.Enabled	true일 때, 데이터 보호 경고가 이메일로 전송됩니다.
Teams.DataProtection.Email	데이터 보호 경고의 이메일 주소입니다.

속도 제한 옵션

남용을 방지하기 위해 요청 속도 제한을 제어합니다.

{
  "IPRateLimiterOptions": {
    "Enabled": false,
    "PermitLimit": 500,
    "SegmentsPerWindow": 10,
    "WindowSeconds": 60,
    "QueueLimit": 0,
    "QueueProcessingOrder": "OldestFirst"
  },
  "UserRateLimiterOptions": {
    "Enabled": false,
    "PermitLimit": 1000,
    "SegmentsPerWindow": 6,
    "WindowSeconds": 60,
    "QueueLimit": 0,
    "QueueProcessingOrder": "OldestFirst"
  }
}

옵션	유형	설명
Enabled	부울	속도 제한이 활성화되는지 여부입니다. 활성화하려면 true로 설정합니다. 내부/신뢰할 수 있는 네트워크의 경우 false로 유지할 수 있습니다.
PermitLimit	정수	창당 허용되는 최대 요청 수입니다. IP 제한자는 500으로, 사용자 제한자는 1000으로 기본 설정됩니다.
SegmentsPerWindow	정수	시간 창이 나뉘는 세그먼트 수입니다. 슬라이딩 창 알고리즘에 사용됩니다. 값이 높을수록 제한이 부드럽습니다.
WindowSeconds	정수	초 단위의 시간 창 크기입니다. 요청은 이 롤링 창 내에서 계산됩니다.
QueueLimit	정수	제한이 초과될 때 큐에 넣을 요청 수입니다. 0은 즉시 거부를 의미합니다. 높은 값은 나중에 처리하기 위해 요청을 큐에 넣습니다.
QueueProcessingOrder	문자열	큐에 넣은 요청을 처리할 순서입니다. "OldestFirst"(FIFO) 또는 "NewestFirst"(LIFO).

IP 속도 제한자: IP 주소당 요청을 제한합니다. 개별 나쁜 행위자로부터 보호합니다.

사용자 속도 제한자: 인증된 사용자당 요청을 제한합니다. 인증된 사용자의 남용으로부터 보호합니다.

GitHub 통합

GitHub 리포지토리에 프로젝트를 게시할 수 있습니다.

다음에서 disablePublishToGithub: false를 설정합니다.

{
  "FrontendOptions": {
    "Extras": "{ disablePublishToGithub: false, disableSurvey: true, disableAnalytics: true, disableFeedback: true, requiresActivation: true }"
  }
}

{
  "GithubOptions": {
    "Enabled": true,
    "BaseUrl": "https://github.com/",
    "AuthorizeClientEndpoint": "/login/oauth/authorize",
    "AccessTokenEndpoint": "/login/oauth/access_token",
    "Scope": "user repo workflow",
    "RedirectUri": "/oauth/github/auth-callback",
    "ClientId": "<your-github-oauth-app-client-id>",
    "ClientSecret": "<your-github-oauth-app-client-secret>",
    "PackageAccessTokenSuffix": ""
  }
}

옵션	유형	설명
BaseUrl	문자열	GitHub 기본 URL입니다. github.com의 경우 "https://github.com/"을 사용하거나 GitHub Enterprise URL을 사용합니다.
AuthorizeClientEndpoint	문자열	OAuth 권한 부여 엔드포인트 경로입니다. 표준 값이며, 사용자 지정 GitHub Enterprise를 사용하지 않는 한 변경하지 마십시오.
AccessTokenEndpoint	문자열	OAuth 토큰 엔드포인트 경로입니다. 표준 값이므로 변경하지 마십시오.
Scope	문자열	요청할 OAuth 범위입니다. "user repo workflow"는 사용자 정보 읽기, 리포지토리 액세스 및 워크플로 트리거를 허용합니다.
RedirectUri	문자열	OAuth 콜백 경로입니다. 이는 GitHub OAuth App 설정에 구성된 것과 일치해야 합니다.
ClientId	문자열	GitHub OAuth App 클라이언트 ID입니다. GitHub > 설정 > 개발자 설정 > OAuth 앱에서 OAuth App을 만듭니다.
ClientSecret	문자열	GitHub OAuth App 클라이언트 시크릿입니다. 이 시크릿을 보관하세요!

설정 단계:

1. GitHub > 설정 > 개발자 설정 > OAuth 앱 > 새 OAuth 앱으로 이동합니다.
2. 홈페이지 URL을 AppBuilder URL로 설정합니다.
3. 권한 부여 콜백 URL을 https://your-appbuilder-url/oauth/github/auth-callback으로 설정합니다.
4. 클라이언트 ID 및 클라이언트 시크릿을 구성에 복사합니다.
5. 컨테이너를 다시 시작하여 변경 사항을 포함합니다. docker run --restart always -p 8080:5000 --network appbuilder-network -v C:/appbuilder/config:/appbuilder/config --name appbuilder -d appbuilder:2.0

Azure DevOps 통합

Azure DevOps 리포지토리에 프로젝트를 게시할 수 있습니다.

다음에서 disablePublishToDevOps: false를 설정합니다.

{
  "FrontendOptions": {
    "Extras": "{ disablePublishToDevOps: false, disableSurvey: true, disableAnalytics: true, disableFeedback: true, requiresActivation: true }"
  }
}

{
  "DevOpsOptions": {
    "Enabled": true,
    "TokenEncryptionKeyBase64": "<generate-a-random-16-byte-base64-key>",
    "BaseUrl": "https://login.microsoftonline.com/",
    "TenantId": "common",
    "AuthorizeClientEndpoint": "oauth2/v2.0/authorize",
    "RedirectUri": "/oauth/devops/auth-callback",
    "AccessTokenEndpoint": "oauth2/v2.0/token",
    "RevokeTokenEndpoint": "https://graph.microsoft.com/v1.0/users/{userObjectId}/revokeSignInSessions",
    "Scopes": "499b84ac-1321-427f-aa17-267ca6975798/user_impersonation offline_access openid profile user.read",
    "ClientId": "<your-azure-ad-app-client-id>",
    "ClientSecret": "<your-azure-ad-app-client-secret>",
    "RestApiVersion": "7.1",
    "ExcludedOrganizations": []
  }
}

옵션	유형	설명
TokenEncryptionKeyBase64	문자열	저장된 OAuth 토큰을 암호화하기 위한 키입니다. openssl rand -base64 16으로 생성합니다.
BaseUrl	문자열	Azure AD 로그인 URL입니다. Microsoft ID 플랫폼의 표준 값입니다.
TenantId	문자열	Azure AD 테넌트입니다. 모든 Microsoft 계정을 허용하려면 "common"을 사용하거나 단일 테넌트의 경우 테넌트 ID를 지정합니다.
Scopes	문자열	Azure DevOps의 OAuth 범위입니다. GUID는 Azure DevOps의 리소스 ID입니다. 알고 있는 경우가 아니면 수정하지 마십시오.
ClientId	문자열	Azure AD 앱 등록 클라이언트 ID입니다.
ClientSecret	문자열	Azure AD 앱 등록 클라이언트 시크릿입니다.
RestApiVersion	문자열	Azure DevOps REST API 버전입니다. "7.1"은 현재 안정 버전입니다.
ExcludedOrganizations	배열	숨길 Azure DevOps 조직 목록입니다. 사용자는 게시할 때 이러한 조직을 보지 못합니다.

컨테이너를 다시 시작하여 변경 사항을 포함합니다. docker run --restart always -p 8080:5000 --network appbuilder-network -v C:/appbuilder/config:/appbuilder/config --name appbuilder -d appbuilder:2.0

이메일 구성

이메일 알림을 활성화합니다(선택 사항).

{
  "EmailOptions": {
    "Smtp": {
      "Server": "smtp.your-server.com",
      "Port": "587",
      "User": "your-smtp-user",
      "Password": "your-smtp-password"
    }
  }
}

옵션	유형	설명
Server	문자열	SMTP 서버 호스트 이름입니다.
Port	문자열	SMTP 서버 포트입니다. 일반적인 값: "587"(TLS), "465"(SSL), "25"(암호화되지 않음 - 권장하지 않음).
User	문자열	SMTP 인증 사용자 이름입니다.
Password	문자열	SMTP 인증 암호입니다.

AI 구성

AI 기능은 선택 사항입니다. 활성화하려면 configs/ai/의 파일을 구성합니다.

ai.appsettings.json

사용할 AI 공급자 및 모델을 제어합니다.

{
  "AIOptions": {
    "Provider": "OPENAI",
    "Model": "gpt-4.1-mini",
    "SupportsVision": true
  },
  "ImageGeneration": {
    "Provider": "OPENAI",
    "Model": "gpt-image-1"
  },
  "GoogleCloudTranscribe": {
    "Enabled": false,
    "Credentials": "GoogleCloud",
    "Model": "latest_long",
    "DefaultLanguageCode": "en-US"
  }
}

옵션	유형	설명
AIOptions.Provider	문자열	텍스트 생성 공급자입니다. 값: "OPENAI", "ANTHROPIC", "GOOGLECLOUD", "GROQ"
AIOptions.Model	문자열	텍스트 생성 모델 ID입니다. 선택한 공급자의 유효한 모델이어야 합니다(아래 표 참조).
AIOptions.SupportsVision	부울	모델이 이미지를 분석할 수 있는지 여부입니다. 비전 기능이 있는 모델을 활성화합니다.
ImageGeneration.Provider	문자열	이미지 생성 공급자입니다. 값: "OPENAI", "GOOGLECLOUD", "RUNWARE"
ImageGeneration.Model	문자열	이미지 생성 모델 ID입니다.
GoogleCloudTranscribe.Enabled	부울	음성-텍스트를 활성화합니다. Google Cloud 자격 증명이 필요합니다.
GoogleCloudTranscribe.DefaultLanguageCode	문자열	음성 인식의 기본 언어입니다. 예: "en-US", "de-DE", "fr-FR".

사용 가능한 모델:

공급자	텍스트 모델	이미지 모델
OpenAI	gpt-5.2, gpt-5.1, gpt-5-mini, gpt-5-nano, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano	gpt-image-1
Anthropic	claude-sonnet-4-5-20250929, claude-haiku-4-5-20251001	-
Google Cloud	gemini-2.5-pro, gemini-2.5-flash, gemini-3-pro-preview	imagen-4.0-generate-001, imagen-4.0-ultra-generate-001, imagen-4.0-fast-generate-001
Groq	llama-3.3-70b-versatile, llama-3.1-8b-instant	-
Runware	-	runware:100@1, runware:101@1

ai.credentials.appsettings.json

AI 공급자의 API 키를 저장합니다.

{
  "AICredentialsOptions": {
    "OpenAI": {
      "ApiKey": "<your-openai-api-key>"
    },
    "Anthropic": {
      "ApiKey": "<your-anthropic-api-key>"
    },
    "Groq": {
      "ApiKey": "<your-groq-api-key>"
    },
    "Runware": {
      "ApiKey": "<your-runware-api-key>"
    },
    "GoogleCloud": {
      "JsonCredentials": {
        "type": "service_account",
        "project_id": "your-project-id",
        "private_key_id": "...",
        "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
        "client_email": "...",
        "client_id": "...",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token"
      }
    }
  }
}

사용할 공급자만 구성합니다. 다음에서 API 키를 가져옵니다:

• OpenAI: https://platform.openai.com/api-keys
• Anthropic: https://console.anthropic.com/
• Groq: https://console.groq.com/
• Runware: https://runware.ai/
• Google Cloud: Google Cloud Console에서 서비스 계정 만들기

프론트엔드 환경 설정

이러한 설정은 프론트엔드 애플리케이션에 전달되며 UI 기능 및 동작을 제어합니다.

{
  "FrontendOptions": {
    "Extras": "{ disableSurvey: true, disableAnalytics: true, disableFeedback: true, requiresActivation: true, disableAI: false, enableAIChat: true }"
  }
}

Extras 필드는 프론트엔드 구성 플래그를 포함하는 JSON 문자열입니다:

설정	기본값(온프레미스)	설명
disableAI	true	AI 기능의 마스터 스위치입니다. true일 때 모든 AI 관련 UI가 숨겨지고 AI API가 호출되지 않습니다.
enableAIChat	false	도구 상자에서 AI 채팅 패널을 표시합니다. 패널을 통해 사용자는 구성 요소 및 레이아웃을 생성하기 위해 AI와 상호 작용할 수 있습니다.
enableSpeechToText	false	AI 채팅에서 음성 입력을 위해 마이크 버튼을 표시합니다. Google Cloud Speech-to-Text가 구성되어야 합니다.

작동 방식: 이러한 값은 백엔드 API를 통해 런타임에 프론트엔드에 주입됩니다. 프론트엔드는 초기화 시 이러한 플래그를 읽고 기능을 활성화/비활성화합니다. AI 기능이 작동하려면 이 파일들 ai.appsettings.json, ai.credentials.appsettings.json, ai.providers.appsettings.json, ai.models.appsettings.json에서 필요한 자격 증명, 모델 및 설정을 제공해야 합니다.

Docker 이미지 설치 및 컨테이너 실행

볼륨 마운트

컨테이너 경로	목적	필수
/app/appsettings.json	기본 구성	예
/app/configs/ai/	AI 구성 파일	AI를 활성화한 경우에만
/app/storage/	파일 스토리지(업로드, 내보내기)	예(지속성을 위해)
/app/logs/	로그 파일	권장

Docker 실행 명령

이미지 로드

docker load -i appbuilder.tar

DB 연결에 대한 환경 변수만 제공하여 컨테이너 실행

docker run --restart always -p 80:5000 \
  -e "ConnectionStrings:AppBuilderSqlServerConnection=Data Source=<server>,<port>;Database=<db-name>;User ID=<user>;Password=<password>;Encrypt=False;TrustServerCertificate=False;MultipleActiveResultSets=True" \
  -v C:/appbuilder/logs:/appbuilder/logs \
  -v C:/appbuilder/storage:/appbuilder/storage \
  --name appbuilder \
  appbuilder:1.0

사용자 정의 구성이 마운트될 때 컨테이너 실행 -v C:/appbuilder/config:/appbuilder/config \

별도의 docker 컨테이너에서 실행 중인 데이터베이스에 연결하려는 경우: appsettings 파일은 연결 문자열을 AppBuilderMySqlConnection": "Server=mysql;Port=3306;Database=AppBuilder;User=user;Password=password;로 설정합니다. docker 네트워크를 만들고 mysql을 포함합니다. 시작 명령에서 네트워크를 제공합니다.

docker run --restart always -p 80:5000 \
  --network appbuilder-network \
  -v C:/appbuilder/config:/appbuilder/config \
  -v C:/appbuilder/logs:/appbuilder/logs \
  -v C:/appbuilder/storage:/appbuilder/storage \
  --name appbuilder \
  appbuilder:1.0

호스트 PC의 서버에서 데이터베이스 실행에 연결하려는 경우 host.docker.internal을 사용합니다: appsettings 파일은 연결 문자열을 AppBuilderMySqlConnection": "server=host.docker.internal;Port=3306;Database=AppBuilder;User=user;Password=password;로 설정합니다.

docker run --restart always -p 80:5000 \
  -v C:/appbuilder/config:/appbuilder/config \
  -v C:/appbuilder/logs:/appbuilder/logs \
  -v C:/appbuilder/storage:/appbuilder/storage \
  --name appbuilder \
  appbuilder:1.0

빠른 시작 체크리스트

최소 설정

1. appsettings.json에서 ConnectionStrings를 업데이트하거나 환경 재정의 옵션(플래그)을 사용합니다.

인증 포함

1. 최소 설정 완료
2. SkipAuth를 false로 설정합니다.
3. OAuth 공급자(Azure AD, Okta, Keycloak 등) 구성
4. AuthSettings에서 Authority, ClientId 설정

AI 기능 포함

1. 최소 설정 완료
2. 선택한 AI 공급자에서 API 키 받기
3. 공급자 및 모델로 ai.appsettings.json 구성
4. ai.credentials.appsettings.json에 API 키 추가
5. appsetting.json 파일의 FrontendOptions에서 disableAI: false 및 enableAIChat: true 설정

GitHub/DevOps 통합 포함

1. OAuth App(GitHub) 또는 앱 등록(Azure AD) 만들기
2. 공급자에서 콜백 URL 구성
3. 클라이언트 ID 및 시크릿을 구성에 추가합니다.

문제 해결

로그 위치

로그 파일	내용
./logs/appbuilder.log	API 요청, 인증, 관련 일반 오류
./logs/codegen.log	API 요청, 인증, 관련 일반 오류
./logs/ai.log	AI 공급자 요청 및 응답

일반적인 문제

데이터베이스 연결 실패

• 연결 문자열 형식이 공급자와 일치하는지 확인합니다.
• 데이터베이스 서버가 컨테이너에서 액세스 가능한지 확인합니다.
• Docker Desktop on Windows/Mac의 경우 localhost 대신 host.docker.internal을 사용합니다.
• 데이터베이스 사용자에게 테이블을 만들 수 있는 권한이 있는지 확인합니다.

브라우저의 CORS 오류

• 프로토콜과 포트를 포함하여 정확한 원본을 CorsPolicy.Origins에 추가합니다.
• 차단되는 실제 원본을 확인하려면 브라우저 콘솔을 확인합니다.

AI 기능이 작동하지 않음

• 프론트엔드 환경에서 disableAI: false를 확인합니다.
• API 키가 유효하고 크레딧이 있는지 확인합니다.
• 특정 오류 메시지는 ai.log를 검토합니다.
• 모델 이름이 사용 가능한 모델과 정확히 일치하는지 확인합니다.

파일 업로드 실패

• 스토리지 디렉터리가 있고 쓰기 가능한지 확인합니다.
• 큰 이미지를 업로드하는 경우 MaxImageSizeMb를 확인합니다.
• 볼륨이 Docker에서 올바르게 마운트되었는지 확인합니다.

인증이 작동하지 않음

• SkipAuth가 false인지 확인합니다.
• Authority URL이 액세스 가능한지 확인합니다.
• 콜백 URL이 구성 및 OAuth 공급자 모두에서 일치하는지 확인합니다.
• 브라우저 콘솔에서 OAuth 오류를 확인합니다.

Windows의 Docker Desktop

Windows의 Docker Desktop은 Windows 머신에 로그인하지 않고는 자동으로 시작되지 않습니다. Docker Desktop on Windows - Docker 팀은 프로덕션 워크로드에 Docker Desktop을 권장하지 않습니다. Windows 컨테이너를 원하는 경우 Linux 박스에서 Docker를 사용하거나 Windows Server용 Docker를 사용해야 합니다.

추가 리소스

• OpenID Connect를 사용한 온프레미스 인증
• App Builder 배포 구성 플래그
• 외부 리소스 화이트리스팅
• App Builder 인터페이스 개요
• 단일 페이지 및 탐색
• App Builder 구성 요소
• Flex 레이아웃
• 데스크톱 앱 실행
• 앱 생성
• Indigo.Design 시작하기