Ubuntu - 우분투 부팅시 Docker Compose 자동 실행하기

OS : Ubuntu 22.04.4 LTS

서버가 재부팅되면 Docker 데몬은 자동으로 실행되지만,
docker compose up -d로 실행한 서비스는 자동으로 올라오지 않는 경우가 많습니다.

이 문제를 해결하는 가장 안정적인 방법은 systemd 서비스 유닛으로 등록하는 것입니다.
이 방식은 운영체제 서비스처럼 Docker Compose 프로젝트를 관리할 수 있게 해줍니다.

---

💡 왜 systemd로 관리해야 할까?

Docker에는 자체적으로 restart: always 같은 재시작 정책이 있습니다.
하지만 이 방식은 컨테이너 단위 관리만 가능할 뿐, 프로젝트 전체를 제어하거나 로그를 한눈에 보는 데는 한계가 있습니다.

systemd를 사용하면 다음과 같은 장점이 있습니다:

• ✅ 자동 실행 : 서버 부팅 시 프로젝트 전체 자동 실행
• ✅ 서비스 제어 : systemctl start|stop|restart로 간편 제어
• ✅ 로그 통합 : journalctl을 통해 서비스 단위 로그 확인 가능
• ✅ 부팅 순서 보장 : Docker 서비스가 먼저 실행된 후 Compose 실행

즉, 운영 환경에서는 restart: always 보다는 systemd 방식이 더 권장됩니다.

---

🚀 빠른 시작

1. 서비스 유닛 파일 생성

sudo nano /etc/systemd/system/myapp.service

---

2. 서비스 유닛 작성

[Unit]
Description=Docker Compose Application 서비스 자동 부팅 관리
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/home/ubuntu/myproject
ExecStart=/usr/bin/docker compose -f compose.yaml up -d
ExecStop=/usr/bin/docker compose -f compose.yaml down 
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

---

⚠️ 주의사항

• WorkingDirectory는 실제 docker-compose.yml 파일이 있는 경로로 수정해야 합니다.
• /usr/bin/docker 경로는 which docker로 확인 후 맞추는 것이 안전합니다.
• Type=oneshot + RemainAfterExit=yes는 한 번 실행 후에도 서비스 상태를 유지합니다. → 단일 컨테이너 포그라운드 실행 시 Type=simple을 사용해도 무방합니다.

---

3. systemd 적용 및 자동 실행 설정

# systemd에 서비스 파일 인식시키기
sudo systemctl daemon-reload

# 부팅할 때 자동으로 실행되도록 등록
sudo systemctl enable myapp.service

# 서비스를 즉시 실행
sudo systemctl start myapp.service

---

4. 동작 확인

# 서비스 상태 확인
systemctl status myapp.service

# 서버 재부팅
sudo reboot

# 부팅 완료 후 컨테이너 실행 확인
docker ps

---

📜 로그 확인 및 문제 해결

서비스 실행이 잘 되지 않을 때는 journalctl 로그를 확인하세요.

# 최근 100줄 로그
journalctl -u myapp.service -n 100

# 실시간 로그
journalctl -u myapp.service -f

👉 docker logs와 달리, 서비스 단위 로그를 확인할 수 있어 운영 관리가 훨씬 편리합니다.

---

🔀 대안 방법 비교

• Docker Compose restart 정책 개별 컨테이너 단위 자동 재시작에는 유용하지만, 프로젝트 전체 관리에는 한계가 있음.
• cron @reboot 부팅 시 docker compose up -d를 실행하도록 설정 가능. 간단하지만 로그 관리와 제어 기능이 부족함.

👉 따라서:

• 개인 테스트 환경 → cron
• 운영 환경 → systemd

---

✅ 정리

Docker Compose 자동 재시작 방법

• 단순 자동 재시작 : compose.yml 내에 restart: always 또는 restart: unless-stopped 명시
• 실무 운영 환경 : systemd 서비스 등록
• systemd 장점 : 자동 실행 + 로그 관리 + 제어 + 안정성 확보