Appsmith: 개발자를 위한 오픈소스 로우코드 내부 도구 빌더 Docker 설치 가이드 ⋆ Blog * JackerLab

개요

Appsmith는 개발자 중심의 오픈소스 로우코드 플랫폼으로, 커스텀 대시보드, 관리자 패널, CRUD 앱을 빠르게 구축할 수 있습니다. Apache 2.0 라이선스로 배포되며, 35K+ GitHub Stars를 보유하고 있습니다. Retool의 오픈소스 대안으로, JavaScript에 익숙한 개발자에게 최적화되어 있습니다.

Appsmith의 핵심 철학

Appsmith는 “개발자 우선(Developer-First)” 철학을 추구합니다. UI는 드래그 앤 드롭으로 빠르게 구성하되, 비즈니스 로직은 JavaScript로 완전히 제어할 수 있습니다. Git 기반 버전 관리와 CI/CD 통합으로 기존 DevOps 워크플로우에 자연스럽게 통합됩니다.

주요 특징

기능	설명
드래그 앤 드롭 빌더	45+ 사전 구축 위젯
JavaScript 지원	커스텀 로직, 데이터 변환
Git 통합	버전 관리, 브랜치, PR
45+ 데이터 소스	DB, API, SaaS 도구 연동
REST/GraphQL	API 연동 및 생성
RBAC	역할 기반 접근 제어
SSO	SAML, OIDC 지원
셀프호스팅	Docker, Kubernetes, AWS
커스텀 위젯	JS/HTML/CSS로 위젯 생성
AI 지원	자연어로 위젯/쿼리 생성

로우코드 플랫폼 비교

기능	Appsmith	Budibase	ToolJet	Retool
오픈소스	✅	✅	✅	❌
Git 통합	✅	❌	✅	✅
JavaScript	전면 지원	제한적	지원	지원
내장 DB	❌	✅	✅	❌
위젯 수	45+	40+	45+	50+
커스텀 위젯	✅	플러그인	✅	✅
셀프호스팅 무료	무제한	20명	무제한	❌
코딩 필요도	높음	낮음	중간	중간
대상 사용자	개발자	IT 전문가	개발자	개발자

시스템 요구 사항

항목	최소 사양	권장 사양
RAM	2GB	4GB 이상
CPU	1 코어	2 코어 이상
저장소	10GB	50GB 이상
Docker	20.10+	최신 버전
Docker Compose	2.0+	최신 버전

Docker Compose 설치

빠른 시작 (단일 명령)

curl -L https://bit.ly/3AQzII6 -o docker-compose.yml
docker-compose up -d

수동 설치

mkdir -p ~/appsmith && cd ~/appsmith

.env 파일:

# 암호화 설정 (필수)
APPSMITH_ENCRYPTION_PASSWORD=your-encryption-password-min-16-chars
APPSMITH_ENCRYPTION_SALT=your-encryption-salt-min-16-chars

# MongoDB 설정 (내장 사용 시 생략 가능)
# APPSMITH_MONGODB_URI=mongodb://mongo:27017/appsmith

# Redis 설정 (내장 사용 시 생략 가능)
# APPSMITH_REDIS_URL=redis://redis:6379

# 이메일 설정 (선택사항)
APPSMITH_MAIL_ENABLED=true
APPSMITH_MAIL_HOST=smtp.example.com
APPSMITH_MAIL_PORT=587
APPSMITH_MAIL_USERNAME=your-email@example.com
APPSMITH_MAIL_PASSWORD=your-email-password
APPSMITH_MAIL_FROM=noreply@example.com

# 도메인 설정 (HTTPS용)
APPSMITH_CUSTOM_DOMAIN=appsmith.yourdomain.com

# 분석 비활성화 (선택사항)
APPSMITH_DISABLE_TELEMETRY=true

docker-compose.yml:

version: "3.8"

services:
  appsmith:
    image: appsmith/appsmith-ee:latest
    container_name: appsmith
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - appsmith_data:/appsmith-stacks
    environment:
      APPSMITH_ENCRYPTION_PASSWORD: ${APPSMITH_ENCRYPTION_PASSWORD}
      APPSMITH_ENCRYPTION_SALT: ${APPSMITH_ENCRYPTION_SALT}
      APPSMITH_MAIL_ENABLED: ${APPSMITH_MAIL_ENABLED:-false}
      APPSMITH_MAIL_HOST: ${APPSMITH_MAIL_HOST:-}
      APPSMITH_MAIL_PORT: ${APPSMITH_MAIL_PORT:-}
      APPSMITH_MAIL_USERNAME: ${APPSMITH_MAIL_USERNAME:-}
      APPSMITH_MAIL_PASSWORD: ${APPSMITH_MAIL_PASSWORD:-}
      APPSMITH_MAIL_FROM: ${APPSMITH_MAIL_FROM:-}
      APPSMITH_DISABLE_TELEMETRY: ${APPSMITH_DISABLE_TELEMETRY:-false}
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

volumes:
  appsmith_data:
    driver: local

Community Edition 사용

services:
  appsmith:
    image: appsmith/appsmith-ce:latest  # CE 버전
    # ... 나머지 설정 동일

외부 데이터베이스 사용 (프로덕션)

version: "3.8"

services:
  appsmith:
    image: appsmith/appsmith-ee:latest
    container_name: appsmith
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    environment:
      APPSMITH_ENCRYPTION_PASSWORD: ${APPSMITH_ENCRYPTION_PASSWORD}
      APPSMITH_ENCRYPTION_SALT: ${APPSMITH_ENCRYPTION_SALT}
      APPSMITH_MONGODB_URI: mongodb://mongo:27017/appsmith
      APPSMITH_REDIS_URL: redis://redis:6379
    volumes:
      - appsmith_data:/appsmith-stacks
    depends_on:
      - mongo
      - redis
    networks:
      - appsmith-network

  mongo:
    image: mongo:6.0
    container_name: appsmith-mongo
    restart: unless-stopped
    volumes:
      - mongo_data:/data/db
    networks:
      - appsmith-network

  redis:
    image: redis:7-alpine
    container_name: appsmith-redis
    restart: unless-stopped
    volumes:
      - redis_data:/data
    networks:
      - appsmith-network

volumes:
  appsmith_data:
  mongo_data:
  redis_data:

networks:
  appsmith-network:
    driver: bridge

Traefik 리버스 프록시 설정

version: "3.8"

services:
  appsmith:
    image: appsmith/appsmith-ee:latest
    container_name: appsmith
    restart: unless-stopped
    environment:
      APPSMITH_ENCRYPTION_PASSWORD: ${APPSMITH_ENCRYPTION_PASSWORD}
      APPSMITH_ENCRYPTION_SALT: ${APPSMITH_ENCRYPTION_SALT}
    volumes:
      - appsmith_data:/appsmith-stacks
    networks:
      - appsmith-network
      - traefik-network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.appsmith.rule=Host(`appsmith.yourdomain.com`)"
      - "traefik.http.routers.appsmith.entrypoints=websecure"
      - "traefik.http.routers.appsmith.tls.certresolver=myresolver"
      - "traefik.http.services.appsmith.loadbalancer.server.port=80"

실행

docker-compose up -d

# 로그 확인
docker-compose logs -f appsmith

# 상태 확인
docker-compose ps

초기 설정

1) 웹 접속

브라우저에서 http://localhost 또는 설정한 도메인으로 접속합니다.

2) 관리자 계정 생성

Get Started 클릭
이름, 이메일, 비밀번호 입력
계정 생성 완료

3) 워크스페이스 생성

워크스페이스 이름 입력
팀원 초대 (선택사항)

주요 기능 활용

앱 생성 워크플로우

1. Workspace > Create New > Application
2. 데이터 소스 연결 (Datasources)
3. 쿼리 작성 (Queries)
4. UI 구성 (Widgets)
5. JavaScript로 로직 연결
6. 테스트 및 배포

데이터 소스 연결

지원되는 데이터 소스:

카테고리	데이터 소스
관계형 DB	PostgreSQL, MySQL, MSSQL, Oracle, MariaDB
NoSQL	MongoDB, DynamoDB, Firestore, Redis
API	REST API, GraphQL, SMTP
SaaS	Google Sheets, Airtable, Twilio, Slack
클라우드	AWS S3, GCS, Snowflake

쿼리 작성 예시

PostgreSQL 쿼리:

SELECT * FROM users 
WHERE department = {{Dropdown1.selectedOptionValue}}
AND created_at > {{DatePicker1.selectedDate}}
ORDER BY name ASC
LIMIT {{Table1.pageSize}}
OFFSET {{Table1.pageOffset}}

REST API 호출:

// API 설정
URL: https://api.example.com/users/{{Input1.text}}
Method: GET
Headers: {
  "Authorization": "Bearer {{appsmith.store.token}}"
}

JavaScript 활용

데이터 변환:

// Query 결과 변환
{{
  Query1.data.map(user => ({
    fullName: `${user.firstName} ${user.lastName}`,
    email: user.email,
    status: user.isActive ? "Active" : "Inactive"
  }))
}}

조건부 표시:

// 위젯 Visible 속성
{{appsmith.user.email.endsWith("@admin.com")}}

버튼 onClick:

{{
  (async () => {
    await Query1.run();
    showAlert("Data saved successfully!", "success");
    closeModal("EditModal");
    await FetchUsers.run();
  })()
}}

Git 통합

Settings > Git Connection
Git 저장소 URL 입력
SSH 키 또는 토큰 인증
브랜치 선택

Git 워크플로우:

Commit: 변경사항 저장
Push: 원격 저장소에 푸시
Pull: 최신 변경사항 가져오기
Merge: 브랜치 병합
Branch: 새 브랜치 생성

RBAC 설정

역할	권한
Administrator	모든 권한
Developer	앱 생성/수정, 데이터소스 관리
App Viewer	앱 실행만 가능

SSO 설정

Google OAuth

Settings > Authentication > Google OAuth
Client ID: your-google-client-id
Client Secret: your-google-client-secret

SAML SSO (Enterprise)

Settings > Authentication > SAML 2.0
Entity ID: https://appsmith.yourdomain.com
ACS URL: https://appsmith.yourdomain.com/api/v1/saml/login
Metadata URL: https://idp.example.com/metadata.xml

OIDC

Settings > Authentication > OIDC
Client ID: your-client-id
Client Secret: your-client-secret
Authorization URL: https://auth.example.com/authorize
Token URL: https://auth.example.com/token
User Info URL: https://auth.example.com/userinfo

트러블슈팅

컨테이너 시작 실패

# 로그 확인
docker logs appsmith

# 볼륨 권한 확인
docker exec appsmith ls -la /appsmith-stacks

# 환경 변수 확인
docker exec appsmith env | grep APPSMITH

MongoDB 연결 오류

# MongoDB 상태 확인
docker exec appsmith-mongo mongosh --eval "db.adminCommand('ping')"

# 연결 테스트
docker exec appsmith curl -s http://mongo:27017

느린 성능

# 리소스 할당 증가
services:
  appsmith:
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: '2'

SSL 인증서 문제

# 인증서 재생성
docker exec appsmith /opt/appsmith/scripts/renew-ssl.sh

# 또는 수동 설정
docker cp ./fullchain.pem appsmith:/appsmith-stacks/ssl/
docker cp ./privkey.pem appsmith:/appsmith-stacks/ssl/

백업 및 복원

자동 백업 설정

Appsmith는 내장 백업 기능을 제공합니다:

# 백업 생성
docker exec appsmith appsmithctl backup

# 백업 파일 위치
docker exec appsmith ls /appsmith-stacks/data/backup/

수동 백업

#!/bin/bash
BACKUP_DIR="/backups/appsmith/$(date +%Y%m%d)"
mkdir -p $BACKUP_DIR

# 볼륨 백업
docker run --rm \
  -v appsmith_appsmith_data:/data \
  -v $BACKUP_DIR:/backup \
  alpine tar czf /backup/appsmith_data.tar.gz /data

# MongoDB 백업 (외부 DB 사용 시)
docker exec appsmith-mongo mongodump \
  --db appsmith \
  --out /dump
docker cp appsmith-mongo:/dump $BACKUP_DIR/mongo_dump

echo "Backup completed: $BACKUP_DIR"

복원

# 복원
docker exec appsmith appsmithctl restore /appsmith-stacks/data/backup/backup-file.tar.gz

# 또는 볼륨 복원
docker-compose down
docker run --rm \
  -v appsmith_appsmith_data:/data \
  -v $BACKUP_DIR:/backup \
  alpine tar xzf /backup/appsmith_data.tar.gz -C /
docker-compose up -d

업그레이드

Watchtower 자동 업그레이드

docker-compose.yml에 Watchtower 레이블이 있으면 자동 업그레이드됩니다.

수동 업그레이드

# 백업 먼저 수행
docker exec appsmith appsmithctl backup

# 최신 이미지 가져오기
docker-compose pull

# 재시작
docker-compose down
docker-compose up -d

# 업그레이드 확인
docker logs appsmith | grep -i version

가격 정책

플랜	가격	주요 기능
Community	$0	무제한 사용자, 오픈소스
Business	$15/user/월	감사 로그, 브랜딩 제거, 99 사용자
Enterprise	$2,500/월 (100명)	SAML SSO, Air-gapped, 커스텀 통합

개요