트러블슈팅


📁 프로젝트 구조 & 자주 쓰는 명령어


전체 프로젝트 구조

📁 DainWiki/
├── 📁 bookstack/         # BookStack 컨테이너 설정 및 데이터
│   └── ...                # 도커 이미지에서 마운트됨
├── 📁 bookstack_db/      # MariaDB 데이터
│   └── ...                  # (.frm, .ibd 등 DB 파일들)
├── 📁 certs/             # 인증서 저장소 (자동 생성됨)
├── 📁 html/              # nginx 기본 페이지 저장소
├── 📁 vhost.d/           # 가상 호스트 설정 (자동 생성됨)
├── 📄 docker-compose.yml   # 전체 도커 설정


bookstack container

📁 /app/www/
├── 📄 .env                  # Laravel 환경 변수
├── 📄 artisan               # Laravel CLI 진입 파일
├── 📁 config/               # 앱 및 DB 설정
│   ├── app.php
│   └── database.php 등
├── 📁 routes/               # 웹 라우트 설정
│   └── web.php 등
├── 📁 resources/            # 뷰 템플릿, 언어 리소스
│   ├── views/
│   └── lang/
├── 📁 storage/              # 캐시, 업로드, 로그 저장소
│   ├── logs/
│   ├── app/
│   └── framework/
└── 📁 public/               # 웹 루트 디렉토리
    └── 📁 uploads/          # 이미지 업로드 저장소


bookstack_db container

📁 /
├── 📁 var/
│   └── 📁 lib/
│       └── 📁 mysql/              # ⬅️ 이곳이 핵심: 실제 DB 파일 저장소
│           ├── 📁 bookstack/     # BookStack에서 사용하는 DB 테이블들
│           │   ├── users.ibd
│           │   ├── pages.ibd
│           │   └── ...
│           ├── mysql/           # 시스템 DB (사용자, 권한 관리)
│           ├── performance_schema/
│           └── ibdata1, ib_logfile0 등
├── 📁 etc/
│   └── my.cnf                    # MariaDB 설정 파일
└── 기타 Linux 기반 도커 파일들


1. SSH로 우분투 서버 접속

Linux, macOS, WSL, 리눅스 서버, VSCode 터미널

ssh -i ~/키이름.pem ubuntu@your-lightsail-ip

윈도우 (Windows PowerShell / CMD)

ssh -i "C:\Users\aweso\pem\키이름.pem" ubuntu@your-lightsail-ip


2. home 접속
cd DainWiki


3. 도커 컨테이너 안으로 들어가기
docker exec -it bookstack bash


4. Laravel 앱 경로로 이동
docker exec -it bookstack bash
cd /app/www
ls -al .env


5. Laravel 설정 캐시 정리 및 마이그레이션 강제 실행
php artisan config:clear
php artisan cache:clear
php artisan view:clear
php artisan migrate --force


6. maria db 명령어 쓰는 곳
docker exec -it bookstack_db bash 여기서 실행
mysql -u root -p
비번 rootpassword

접속성공시
Welcome to the MariaDB monitor...
MariaDB [(none)]>


7. 남은 저장소 용량 확인
df -h



#1. 도커 컨테이너 기반 프로젝트에서 자동 SSL 발급 받는 법

문제
원인
해결 방법
사용 이미지
  1. Nginx Reverse Proxy
    → jwilder/nginx-proxy:
    여러 컨테이너에 대한 요청을 자동으로 프록시해주는 리버스 프록시 서버
  2. Let's Encrypt Companion
    → jrcs/letsencrypt-nginx-proxy-companion:
    위의 nginx-proxy와 연동되어, Let's Encrypt를 통해 SSL 인증서를 자동 발급 및 갱신

기존 구성

📁 DainWiki/
├── 📁 bookstack/
├── 📁 bookstack_db/
├── docker-compose.yml

yml 파일 수정 후 

📁 DainWiki/
├── 📁 bookstack/         # BookStack 컨테이너 설정 및 데이터
├── 📁 bookstack_db/      # MariaDB 데이터
├── 📁 certs/             # 인증서 저장소 (자동 생성됨)
├── 📁 html/              # nginx 기본 페이지 저장소
├── 📁 vhost.d/           # 가상 호스트 설정 (자동 생성됨)
├── docker-compose.yml   # 전체 도커 설정

image.png

📌 ① Let's Encrypt 인증서 발급용 설정

service:
- VIRTUAL_HOST=dainwiki.com
- LETSENCRYPT_HOST=dainwiki.com
- LETSENCRYPT_EMAIL=your@email.com

📌 ② APP_URL 값 http → https로 변경함

-      - APP_URL=http://dainwiki.com
+      - APP_URL=https://dainwiki.com

→ 프로젝트가 내부적으로 https 주소를 인식하게 해준다.

📌 ③ nginx-proxy 및 letsencrypt 컨테이너 추가

nginx-proxy:
    image: jwilder/nginx-proxy
    container_name: nginx-proxy
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - ./certs:/etc/nginx/certs
      - ./vhost.d:/etc/nginx/vhost.d
      - ./html:/usr/share/nginx/html
    networks:
      - bookstack_net

  letsencrypt:
    image: jrcs/letsencrypt-nginx-proxy-companion
    container_name: letsencrypt
    restart: always
    environment:
      - NGINX_PROXY_CONTAINER=nginx-proxy
      - DEFAULT_EMAIL=your@email.com
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./certs:/etc/nginx/certs
      - ./vhost.d:/etc/nginx/vhost.d
      - ./html:/usr/share/nginx/html
    depends_on:
      - nginx-proxy
    networks:
      - bookstack_net

→ 자동 프록시 + SSL 발급기 역할



#2. www 도메인 503 리디렉션 문제


문제

image.png

image.png

원인 분석
해결방법
VIRTUAL_HOST=dainwiki.com,www.dainwiki.com
LETSENCRYPT_HOST=dainwiki.com,www.dainwiki.com
LETSENCRYPT_EMAIL=you@example.com

변경 후에는 도커 컨테이너 재시작

docker-compose down
docker-compose up -d

이 설정을 통해


#3. DB 초기화 & 데이터 보존 트러블슈팅


문제


원인 추정


해결 방법


📂 구조
📁 DainWiki/
├── 📁 bookstack/        # BookStack 앱 설정, 이미지
├── 📁 bookstack_db/     # MariaDB 데이터 (위키 포스트, 계정 등)
├── 📄 docker-compose.yml
└── 📄 .env


✅ yml. 파일 데이터 저장 위치
bookstack:
  volumes:
    - ./bookstack_data:/config

bookstack_db:
  volumes:
    - ./db_data:/var/lib/mysql

데이터는 바인드 마운트(bind mount)방식으로 저장된다.


✅ 실제 호스트 저장 경로 
docker inspect bookstack


✅ 남은 공간 확인
df -h

image.png



#4. 인증서 발급 후에도 보안경고 뜨는 문제


문제
원인 분석
해결 방법

SSL 인증서 발급 로그 확인

docker logs letsencrypt

image.png

도커 컨테이너 접속

docker exer -it nginx-proxy sh
docker exer -it nginx-proxy bash

인증서 디렉터리에 파일 있는지 확인하기

ls /etc/nginx/certs/

image.png



#5. Git에 READ.md 파일만 있을때 로컬에서 처음 push 하는 경우


문제


원인

명령어

사용 시점

의미 및 작동 방식

git pull origin main --allow-unrelated-histories

✅ 최초 1회만

서로 관련 없는 두 Git 히스토리를

강제로 병합

git pull origin main --rebase

❌ 사용 불가 (초기에는)

공통 조상이 있어야

rebase 가능함 → 이 상황에선 에러남

처음 1회만 pull 할 때 --allow-unrelated-histories를 써야 한다.

두 저장소가 '공통 커밋'이 없기 때문에 Git은 서로 관련이 없다고 판단하기 때문에 --rebase는 안 된다.

--allow-unrelated-histories는 공통 커밋 이력이 아예 없는 두 저장소를 병합할 때만 사용하기 때문에 한 번 쓰고 나면,

로컬과 원격이 X → A → B → C 처럼 같은 이력을 공유하게 되어 그 이후부터는 필요가 없다.


해결 방법
# 1. 원격 저장소 추가
git remote add origin https://github.com/내아이디/레포이름.git

# 2. 원격 저장소의 변경사항 먼저 가져오기
git pull origin main --allow-unrelated-histories

# 3. 충돌 났다면 해결 후 커밋

# 4. 이제 정상적으로 푸시 가능
git push origin main

이후부터는 git pull 또는 git pull --rebase 한다.


#6. The current branch master has no upstream branch. 문제


문제
The current branch master has no upstream branch.

$ git push fatal: The current branch master has no upstream branch. To push the current branch and set the remote as upstream, use git push --set-upstream origin master To have this happen automatically for branches without a tracking upstream, see 'push.autoSetupRemote' in 'git help config'.


원인


해결 방법
git branch -m master main
git push -u origin main
# (GitHub에서 default branch 설정 변경)
git push origin --delete master   # (선택)


1. 로컬 브랜치 이름 변경하는 법

git branch -m master main

2. 원격(origin)에 새 브랜치로 푸시

git push -u origin main

3. GitHub에서 기본 브랜치를 main으로 바꾸기

  1. GitHub 웹사이트 → 해당 저장소로 이동
  2. Settings → Branches 메뉴 클릭
  3. Default branch를 master → main으로 변경

4. 기존 master 브랜치 삭제

git push origin --delete master


💡 참고

만약에 master로 계속 쓸거면 아래처럼 --set-upstream 명령어를 쓰면 된다. 

git push --set-upstream origin master

이렇게 하면 origin/master 브랜치를 만들고 연결해서 master 브랜치를 원격(origin)에 푸시한다.

나처럼 지금 master 브랜치에 있고, 아직 원격 저장소에 연결되지 않았을 때,

위 명령어를 실행하면 앞으로는 git push, git pull만 쳐도 origin/master와 연결된다.