home/README.md

Links (개인 링크 홈)

정적 파일(HTML/CSS/JS)만으로 만든 개인 링크 대시보드입니다.

사용법

• 가장 간단한 방법: index.html을 브라우저로 열기

  • 즐겨찾기/추가/편집/삭제/정렬/검색/가져오기/내보내기 기능은 정상 동작합니다.
  • 기본 링크 목록은 index.html 내부의 linksData(JSON)에서 읽기 때문에 파이썬 실행 없이도 순서가 그대로 반영됩니다.

• (선택) links.json을 별도 파일로 운용하고 싶다면 로컬 서버로 실행

python3 -m http.server 8000

그 후 브라우저에서 http://localhost:8000으로 접속합니다.

백엔드(Flask) + PostgreSQL 사용자 저장

로그인 후 사용자 정보를 ncue_user에 저장하고(Upsert), 로그인/로그아웃 시간을 기록하며, /api/config/auth로 Auth0 설정을 공유하려면 백엔드 서버가 필요합니다.

현재 백엔드는 Python Flask(기본 포트 8023) 로 제공합니다. (정적 HTML/JS는 그대로 사용 가능)

1) DB 테이블 생성(서버에서 1회)

psql -h "$DB_HOST" -p "$DB_PORT" -U "$DB_USER" -d "$DB_NAME" -f db/schema.sql

2) 실행 방법 A: (로컬/간단) venv로 실행

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
PORT=8023 python flask_app.py

3) 실행 방법 B: (운영/권장) Miniconda 환경 ncue + gunicorn + systemd

B-1) 최초 1회 설치

cd /path/to/home
conda activate ncue
python -m pip install -r requirements.txt
python -m pip install gunicorn

B-2) 단독 실행(테스트)

conda activate ncue
cd /path/to/home
gunicorn -w 2 -b 127.0.0.1:8023 flask_app:app

확인:

curl -s http://127.0.0.1:8023/healthz
curl -s http://127.0.0.1:8023/api/config/auth

B-3) systemd 서비스(예시)

/etc/systemd/system/ncue-flask.service:

[Unit]
Description=NCUE Flask API (gunicorn)
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/path/to/home

# miniconda 경로는 설치 위치에 맞게 수정하세요.
ExecStart=/bin/bash -lc 'source /opt/miniconda3/etc/profile.d/conda.sh && conda activate ncue && gunicorn -w 2 -b 127.0.0.1:8023 flask_app:app'
Restart=always
RestartSec=3

# .env 대신 systemd Environment로 주입(권장)
Environment=DB_HOST=ncue.net
Environment=DB_PORT=5432
Environment=DB_NAME=ncue
Environment=DB_USER=ncue
Environment=DB_PASSWORD=REPLACE_ME
Environment=TABLE=ncue_user
Environment=AUTH0_DOMAIN=ncue.net
Environment=AUTH0_CLIENT_ID=g5RDfax7FZkKzXYvXOgku3Ll8CxuA4IM
Environment=AUTH0_GOOGLE_CONNECTION=google-oauth2
Environment=ADMIN_EMAILS=dosangyoon@gmail.com,dsyoon@ncue.net
Environment=PORT=8023

[Install]
WantedBy=multi-user.target

적용/재시작:

sudo systemctl daemon-reload
sudo systemctl enable --now ncue-flask
sudo systemctl restart ncue-flask
sudo systemctl status ncue-flask --no-pager

로그 확인:

sudo journalctl -u ncue-flask -n 200 --no-pager

4) Apache 설정(정적은 Apache, /api/*만 8023 프록시)

필요 모듈(Ubuntu/Debian):

sudo a2enmod proxy proxy_http headers
sudo systemctl reload apache2

가상호스트 예시:

<VirtualHost *:80>
  ServerName ncue.net

  DocumentRoot /path/to/home
  <Directory /path/to/home>
    Require all granted
  </Directory>

  ProxyPreserveHost On
  RequestHeader set X-Forwarded-Proto "https"

  ProxyPass        /api/    http://127.0.0.1:8023/api/
  ProxyPassReverse /api/    http://127.0.0.1:8023/api/
  ProxyPass        /healthz http://127.0.0.1:8023/healthz
  ProxyPassReverse /healthz http://127.0.0.1:8023/healthz
</VirtualHost>

적용:

sudo apachectl -t && sudo systemctl reload apache2

5) 503(Service Unavailable) 트러블슈팅 체크리스트

브라우저 콘솔에서 503이 뜨면 대부분 Apache가 127.0.0.1:8023 백엔드로 프록시했는데 백엔드가 응답을 못하는 상태입니다.

• 백엔드가 살아있는지:

curl -i http://127.0.0.1:8023/healthz
curl -i http://127.0.0.1:8023/api/config/auth

• 서비스 로그:

sudo journalctl -u ncue-flask -n 200 --no-pager

• Apache 프록시 로그:
  • Ubuntu/Debian: /var/log/apache2/error.log
  • RHEL/CentOS: /var/log/httpd/error_log

참고: flask_app.py는 DB가 일시적으로 죽어도 앱 임포트 단계에서 바로 죽지 않도록(DB pool lazy 생성) 개선되어, “백엔드 프로세스가 안 떠서 Apache가 503”인 케이스를 줄였습니다.

기본적으로 .env의 ADMIN_EMAILS에 포함된 이메일은 can_manage=true로 자동 승격됩니다.

(선택) 역프록시/분리 배포

• Flask가 정적까지 함께 서빙: http://ncue.net:8023로 접속 (same-origin)
• 정적은 별도 호스팅 + API만 Flask: index.html의 window.AUTH_CONFIG.apiBase에 API 주소를 넣고, Flask에서는 CORS_ORIGINS로 허용 도메인을 지정하세요.

최초 로그인 사용자는 DB에 저장되지만 can_manage=false입니다. 관리 권한을 주려면:

update ncue_user set can_manage = true where email = 'me@example.com';

로그인(관리 기능 잠금)

이 프로젝트는 정적 사이트에서 동작하도록, 관리 기능(추가/편집/삭제/가져오기)을 로그인 후(관리자 이메일) 에만 활성화할 수 있습니다.

• 지원 방식: Auth0 SPA SDK + Auth0 Universal Login
• 구글/카카오/네이버: Auth0 대시보드에서 Social/Custom OAuth 연결로 구성합니다.

설정 방법(.env):

1. Auth0에서 Single Page Application 생성
2. .env에 아래 값을 설정
   • AUTH0_DOMAIN
   • AUTH0_CLIENT_ID
   • AUTH0_GOOGLE_CONNECTION (예: google-oauth2)
   • ADMIN_EMAILS (예: dosangyoon@gmail.com,dsyoon@ncue.net)
3. Auth0 Application 설정에서 아래 URL들을 등록
   • Allowed Callback URLs: 사이트 주소 (예: https://example.com/)
   • Allowed Logout URLs: 사이트 주소 (예: https://example.com/)

데이터 저장

• 기본 링크: links.json
• 사용자가 추가/편집/삭제한 내용: 브라우저 localStorage에 저장됩니다.
• 내보내기: 현재 화면 기준 링크를 JSON으로 다운로드합니다.
• 가져오기: 내보내기 JSON(배열 또는 {links:[...]})을 다시 불러옵니다.

설치 방