Invoice Ninja Docker 설치 가이드: 프로페셔널 인보이스 관리 시스템 자체 호스팅 ⋆ Blog * JackerLab

Invoice Ninja는 프리랜서와 중소기업을 위한 강력한 오픈소스 인보이스 및 결제 관리 플랫폼입니다. 아름다운 인보이스 생성, 온라인 결제 수신, 비용 추적, 시간 관리까지 비즈니스 청구에 필요한 모든 기능을 제공합니다. Stripe, PayPal 등 100개 이상의 결제 게이트웨이를 지원하며, iOS/Android 앱으로 어디서든 관리할 수 있습니다.

Invoice Ninja 주요 특징

Invoice Ninja는 청구 업무를 완전히 자동화할 수 있는 기능들을 제공합니다.

인보이스 및 견적

커스터마이즈 가능한 인보이스 템플릿
PDF 자동 생성 및 이메일 발송
반복 인보이스 자동화
견적서 → 인보이스 변환
다중 통화 지원

결제 관리

Stripe, PayPal, Square 등 100+ 결제 게이트웨이
부분 결제 지원
자동 결제 리마인더
신용 관리

비즈니스 도구

비용 추적 및 카테고리화
시간 추적 (타임시트)
프로젝트 관리
벤더 관리
제품/서비스 카탈로그

클라이언트 포털

고객 전용 포털
온라인 인보이스 확인 및 결제
결제 내역 조회
문서 공유

사전 요구 사항

Docker 및 Docker Compose 설치
최소 2GB RAM
5GB 이상 저장 공간
도메인 (HTTPS 권장)

Docker Compose로 Invoice Ninja 설치

기본 설치

# docker-compose.yml
services:
  invoiceninja:
    image: invoiceninja/invoiceninja:latest
    container_name: invoiceninja
    restart: unless-stopped
    depends_on:
      - db
      - redis
    ports:
      - "8080:80"
    env_file:
      - .env
    volumes:
      - ninja-public:/var/www/app/public
      - ninja-storage:/var/www/app/storage
    networks:
      - invoiceninja-net

  db:
    image: mysql:8.0
    container_name: invoiceninja-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - db-data:/var/lib/mysql
    networks:
      - invoiceninja-net

  redis:
    image: redis:alpine
    container_name: invoiceninja-redis
    restart: unless-stopped
    volumes:
      - redis-data:/data
    networks:
      - invoiceninja-net

volumes:
  ninja-public:
  ninja-storage:
  db-data:
  redis-data:

networks:
  invoiceninja-net:
    driver: bridge

환경 변수 파일

# .env
# 앱 설정
APP_URL=http://localhost:8080
APP_KEY=base64:your_generated_app_key_here
APP_ENV=production
APP_DEBUG=false
REQUIRE_HTTPS=false

# 데이터베이스 설정
DB_HOST=db
DB_PORT=3306
DB_DATABASE=ninja
DB_USERNAME=ninja
DB_PASSWORD=your_secure_db_password

# MySQL root 설정
MYSQL_ROOT_PASSWORD=your_secure_root_password
MYSQL_DATABASE=ninja
MYSQL_USER=ninja
MYSQL_PASSWORD=your_secure_db_password

# Redis 설정
REDIS_HOST=redis
REDIS_PORT=6379

# 초기 관리자 계정
IN_USER_EMAIL=admin@yourdomain.com
IN_PASSWORD=your_secure_admin_password

# 메일 설정 (선택)
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="Invoice Ninja"

APP_KEY 생성

# APP_KEY 생성 (컨테이너 실행 전)
docker run --rm -it invoiceninja/invoiceninja php artisan key:generate --show

# 출력된 키를 .env 파일의 APP_KEY에 입력
# 예: base64:ABC123...

설치 및 실행

# 디렉토리 생성 및 이동
mkdir invoiceninja && cd invoiceninja

# docker-compose.yml 및 .env 파일 생성

# APP_KEY 생성 및 .env에 추가
docker run --rm invoiceninja/invoiceninja php artisan key:generate --show

# 컨테이너 실행
docker compose up -d

# 로그 확인
docker compose logs -f invoiceninja

# 초기 설정 완료까지 약 2-3분 대기
# 브라우저에서 http://localhost:8080 접속
# 로그인: .env에서 설정한 IN_USER_EMAIL / IN_PASSWORD

고급 설정

Nginx 리버스 프록시 포함 구성

# docker-compose.yml
services:
  nginx:
    image: nginx:alpine
    container_name: invoiceninja-nginx
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ninja-public:/var/www/app/public:ro
    depends_on:
      - invoiceninja
    networks:
      - invoiceninja-net

  invoiceninja:
    image: invoiceninja/invoiceninja:latest
    container_name: invoiceninja
    restart: unless-stopped
    expose:
      - "9000"
    depends_on:
      - db
      - redis
    env_file:
      - .env
    volumes:
      - ninja-public:/var/www/app/public
      - ninja-storage:/var/www/app/storage
    networks:
      - invoiceninja-net

  # db, redis 서비스는 동일...

Nginx 설정 파일

# nginx.conf
server {
    listen 80;
    server_name _;
    
    root /var/www/app/public;
    index index.php;
    
    client_max_body_size 50M;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass invoiceninja:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
    }
    
    location ~ /\.ht {
        deny all;
    }
}

Octane 이미지 사용 (고성능)

# docker-compose.yml
services:
  invoiceninja:
    image: invoiceninja/invoiceninja-octane:latest
    # Octane은 Swoole 기반으로 더 빠른 성능 제공

스케줄러 및 큐 워커 설정

Invoice Ninja가 정상 작동하려면 스케줄러와 큐 워커가 필요합니다:

# docker-compose.yml에 추가
services:
  scheduler:
    image: invoiceninja/invoiceninja:latest
    container_name: invoiceninja-scheduler
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - ninja-public:/var/www/app/public
      - ninja-storage:/var/www/app/storage
    command: php artisan schedule:work
    depends_on:
      - invoiceninja
    networks:
      - invoiceninja-net

  queue:
    image: invoiceninja/invoiceninja:latest
    container_name: invoiceninja-queue
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - ninja-public:/var/www/app/public
      - ninja-storage:/var/www/app/storage
    command: php artisan queue:work --sleep=3 --tries=3
    depends_on:
      - invoiceninja
    networks:
      - invoiceninja-net

결제 게이트웨이 설정

Stripe 연동

Stripe 대시보드에서 API 키 획득
Invoice Ninja에서 Settings > Payment Settings 이동
Stripe 활성화 후 키 입력

PayPal 연동

PayPal Developer 계정에서 앱 생성
Client ID와 Secret 획득
Invoice Ninja에서 PayPal 설정

관리 명령어

# 데이터베이스 마이그레이션
docker compose exec invoiceninja php artisan migrate

# 캐시 클리어
docker compose exec invoiceninja php artisan optimize:clear

# 큐 재시작
docker compose exec invoiceninja php artisan queue:restart

# 스케줄 수동 실행
docker compose exec invoiceninja php artisan schedule:run

# 데이터베이스 백업
docker compose exec db mysqldump -u ninja -p ninja > backup.sql

# 로그 확인
docker compose logs -f invoiceninja

# 컨테이너 재시작
docker compose restart invoiceninja

업그레이드 절차

# 1. 백업 생성
docker compose exec db mysqldump -u ninja -p ninja > backup_$(date +%Y%m%d).sql

# 2. 새 이미지 풀
docker compose pull

# 3. 컨테이너 재시작
docker compose up -d

# 4. 마이그레이션 실행
docker compose exec invoiceninja php artisan migrate --force

# 5. 캐시 클리어
docker compose exec invoiceninja php artisan optimize:clear

이메일 설정

Gmail SMTP 설정

# .env
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your_email@gmail.com
MAIL_PASSWORD=your_app_specific_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=your_email@gmail.com
MAIL_FROM_NAME="Your Company"

Mailgun 설정

# .env
MAIL_MAILER=mailgun
MAILGUN_DOMAIN=your_mailgun_domain
MAILGUN_SECRET=your_mailgun_api_key
MAILGUN_ENDPOINT=api.mailgun.net

주요 환경 변수

변수	설명
APP_URL	애플리케이션 URL
APP_KEY	암호화 키 (필수)
REQUIRE_HTTPS	HTTPS 강제 여부
IN_USER_EMAIL	초기 관리자 이메일
IN_PASSWORD	초기 관리자 비밀번호
DB_HOST	데이터베이스 호스트
REDIS_HOST	Redis 호스트
PHANTOMJS_PDF_GENERATION	PDF 생성 엔진
QUEUE_CONNECTION	큐 드라이버 (redis 권장)

마무리

Invoice Ninja는 프리랜서와 소규모 비즈니스에 완벽한 청구 솔루션입니다. 아름다운 인보이스 템플릿, 다양한 결제 게이트웨이 통합, 클라이언트 포털 기능을 모두 무료로 제공합니다. Docker를 통해 쉽게 자체 호스팅할 수 있으며, 데이터의 완전한 소유권을 유지할 수 있습니다. iOS/Android 앱을 함께 사용하면 이동 중에도 인보이스를 관리할 수 있습니다.

참고 링크

공식 사이트: https://invoiceninja.com
GitHub: https://github.com/invoiceninja/invoiceninja
Docker 저장소: https://github.com/invoiceninja/dockerfiles
Docker Hub: https://hub.docker.com/r/invoiceninja/invoiceninja
문서: https://invoiceninja.github.io