created by Aha00aAha00a at 2015-10-21
last modified by Aha00aAha00a at 2026-11-01
revision: 16

Setup

새 위키 사이트 개설 체크리스트.

AhaWiki는 같은 앱과 DB가 여러 도메인을 함께 서비스하므로, 앱·DB·conf 파일은 그대로 두고 아래 항목만 추가한다.

1. *.ahawiki.net 은 승인이면 끝난다

something.ahawiki.net 은 사람이 개설 신청 하고 관리자가 /Admin/SiteRequests 에서 승인하면 열린다. SiteRequestLogic.approve 가 Site, SiteDomain, SiteAdmin 과 Permission 을 한 번에 만들고 도메인 캐시를 버린다. 신청이 들어오면 텔레그램으로 알린다. 이 아래 체크리스트는 필요 없다.

그렇게 되는 것은 사이트마다 하던 일을 와일드카드로 한 번에 끝냈기 때문이다.

단계

와일드카드에서

DNS

*.ahawiki.net CNAME 하나

nginx

server_name *.ahawiki.net 블록 하나. 정확히 일치하는 블록이 있는 기존 사이트는 그쪽이 우선이다

인증서

DNS-01 로 받은 와일드카드 인증서 하나. HTTP-01 로는 와일드카드를 받을 수 없다

Google 로그인

아래 로그인

지도 API 키

referrer *.ahawiki.net/* 한 줄

reCAPTCHA

ahawiki.net 하나가 하위 도메인을 포함한다(Google 문서 기준)

설치는 운영 저장소의 ahawiki/wildcard-setup.sh 이고 되돌리는 법도 거기 있다. 앱은 설정 AhaWiki.siteRequest.parentDomain 이 있을 때만 신청을 받고 로그인을 위임한다. 비어 있으면 둘 다 꺼진다.

로그인. Google 은 redirect URI 에 와일드카드를 받지 않고 세션 쿠키는 호스트마다 따로다. 그래서 하위 도메인의 사이트는 Google 콜백을 상위 도메인으로 받고, 상위 도메인이 프로필을 서명해 사이트로 넘긴다(OAuthHandoff). 넘긴 값은 시작한 브라우저의 flash 쿠키와 일회값이 맞아야 열리므로, 주소만 훔치거나 링크로 심어서는 쓸 수 없다. 받을 수 있는 호스트는 SiteDomain 에 있는 곳뿐이고, 돌아가는 곳은 그 호스트 안의 경로뿐이다.

왜 사이트마다 등록하는 쪽을 자동화하지 않았나. OAuth 클라이언트의 redirect URI 를 고치는 공개 API 가 없고, 앱이 certbot 과 nginx 를 부르려면 앱에 root 를 줘야 한다. 인증서 하나가 모든 하위 도메인을 대표하는 것이 대가다. 인증서 키가 새면 *.ahawiki.net 전체를 다시 발급해야 한다.

와일드카드 때문에 아무 하위 도메인이나 이 서버에 닿으므로, 사이트가 없는 이름은 404 다(Wiki.view).

신청의 주소 규칙은 SiteRequestLogic.validateSubdomain 이고 예약어도 거기 있다. DNS 에 따로 있는 이름은 위키가 아니어도 예약어에 없을 수 있으므로, 승인할 때 눈으로 본다.

2. 자기 도메인을 쓰는 사이트

와일드카드에 들지 않는 이름이다. 아래 체크리스트를 손으로 한다.

3. 신청 접수

  • 사이트 이름
  • 도메인
  • 관리자 Gmail 주소
  • 공개/비공개 여부

4. DNS 설정

  • something.ahawiki.net CNAME → 서버 도메인 추가

5. DB 설정

  • Site row 추가
  • SiteDomain row 추가
  • 기본 Permission row 추가 (공개/비공개 여부에 따라)
  • 새 SiteDomain row는 바로 열리지 않는다. 도메인 목록은 인스턴스마다 캐시에 있어서, 각 인스턴스가 다시 읽은 뒤에 열린다(주기는 Dev Cache). 기다리지 않으려면 앱을 다시 띄운다.

6. nginx 설정

  • nginx 설정 파일에 server block 추가
  • letsencrypt 인증서 발급
    sudo certbot --nginx -d something.ahawiki.net
    sudo nginx -t && sudo nginx -s reload

certbot --nginx 는 인증서를 설치한 뒤 nginx 설정을 스스로 다시 읽는다. 둘째 줄은 설정 파일을 손으로 고친 뒤에만 필요하다.

7. Google API 설정

https://console.cloud.google.com/apis/credentials

  • OAuth 2.0 Client에 redirect URI 추가
    https://something.ahawiki.net/google/oauth/callback
  • API 키 HTTP referrer 제한에 도메인 추가
    *.something.ahawiki.net/*

8. reCAPTCHA 설정

https://www.google.com/recaptcha/admin/

  • 기존 도메인 추가 (something.ahawiki.net)
  • 도메인을 추가하지 않으면 그 사이트에서는 token 을 받을 수 없어 웹 저장이 전부 403 이 된다. 2026-09-13 전에는 빈 token 도 통과시켜서 이것이 드러나지 않았다.

9. 관리자 설정

  • 관리자 Google 계정으로 로그인
  • SiteAdmin 등록 (/Admin/Site/:seq/Admins)
  • Permission 설정 확인 (/Admin/Site/:seq/Permission)

10. 최종 확인

  • HTTPS 접속
  • Google OAuth 로그인
  • 페이지 생성 / 편집 / 저장
  • 첨부파일 업로드 (S3)
  • 지도 표시 (InterpreterMap)
  • reCAPTCHA 동작

11. See Also

11.2. Similar Pages

Similar pages by cosine similarity. Words after page name are term frequency.

  • 32.35% Dev SiteAdmin site(14:27), admin(6:25), api(5:5), seq(2:6), 사이트(4:3), logic(2:4), 관리자(4:1), 있다(2:1), admins(1:2), dev(1:1)
  • 30.00% Dev AdminUIRoleMenu site(14:14), admin(6:14), api(5:8), 추가(8:2), 표시(1:7), seq(2:5), 사이트(4:2), permission(4:1), request(3:2), cache(1:3)

11.3. Adjacent Pages

≤ 32
all
1.0x
1.0x
80
-120
ON
0/0
0/0
0.00
0
0 / 0
1.00x