퀵스타트

이 페이지는 설치가 끝난 호스트에서 직접 제어하는 서버까지 진행합니다. 디스크 위의 설정, 검증된 컴파일, 시작·중지·감시할 수 있는 서버, 그리고 파일 서버가 응답했다는 확인입니다. 설치가 끝났다고 가정합니다.

🧾 시작하기 전에

설치 프로그램은 80 포트에서 서비스를 돌린 채로 남겨 두었고, 그 서비스가 /etc/Pingclair/Pingclairfile 설정을 쥐고 있습니다. 실험하는 동안에는 중지해서 포트를 비웁니다.

sudo pc service stop

mkdir -p ~/demo/public
cd ~/demo
echo '<h1>hello from ~/demo/public</h1>' > public/index.html

1. ✍️ 설정 작성하기

~/demo/Pingclairfile을 만듭니다.

{
    admin 127.0.0.1:2019
}

http://localhost:8080 {
    file_server ./public
}

세 가지만 짚어 둡니다. 맨 위의 이름 없는 블록은 전역 옵션이고, admin이 있으면 pingclair start, stop, reload가 실행 중인 서버와 통신할 수 있습니다. 사이트 주소에는 스킴이 들어가고, http://가 평문을 강제합니다. 이게 없으면 Pingclair는 localhost를 이름으로 취급해 자체 인증 기관으로 HTTPS를 제공하며, 평문 HTTP 클라이언트에게는 빈 응답으로 보입니다(HTTPS). file_server의 루트는 작업 디렉터리 기준 상대 경로입니다.

2. ✅ 실행 전에 검증하기

pingclair validate

✅ Configuration 'Pingclairfile' is valid!

validate는 기본적으로 ./Pingclairfile을 읽고 ./Caddyfile도 감지합니다. 설정을 컴파일하고 인증서 경로 존재 여부 같은 의미 검사를 적용합니다. 검증은 권고가 아닙니다. 실패한 설정은 실행되지 않고, 마지막 줄에 이유가 나옵니다.

3. 🧭 설정이 무엇이 되는지 보기

pingclair adapt --pretty

{
  "debug": false,
  "servers": [
    {
      "name": "localhost",
      "names": [
        "localhost"
      ],
      "listen": [
        "[::]:8080"
      ],

컴파일된 JSON은 서버가 실제로 실행하는 형태입니다. 지시어가 문서대로 동작하지 않을 때 가장 먼저 볼 곳입니다. 대신 pingclair fmt가 파일에 가할 변경을 보려면 다음과 같이 합니다.

pingclair fmt --diff

-    file_server ./public
+  file_server ./public

fmt는 정규형을 출력하며, 들여쓰기는 두 칸이 됩니다.

4. 🚀 실행하기

로그가 터미널에 남는 포그라운드로 실행합니다.

pingclair run Pingclairfile

🚀 Starting Pingclair with config: Pingclairfile
🚀 Starting Pingclair v0.2.0-rc.3
📄 Loaded configuration from: Pingclairfile
🔧 Configured 1 server(s)
🔐 Auto HTTPS: enabled

--watch를 붙이면 저장할 때마다 설정이 다시 읽혀 개발 루프가 됩니다.

pingclair run --watch Pingclairfile

♻️ Configuration reloaded successfully
✅ Configuration reloaded completed successfully in 2.478622ms

셸에서 분리해 백그라운드로 돌릴 수도 있습니다.

pingclair start -c Pingclairfile

✅ Pingclair started in the background (pid 4432)

pingclair start, stop, reload는 Admin API를 통해 실행 중인 서버에 도달합니다. 위 설정에 admin이 있는 이유입니다. pingclair run에는 필요하지 않습니다.

5. 🔍 확인하기

curl -i http://localhost:8080/

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 34
Last-Modified: Tue, 22 Sep 2026 03:26:39 GMT
ETag: "22-6ab1f56f"
Vary: Accept-Encoding
Accept-Ranges: bytes
server: Pingclair

ETag와 Last-Modified는 파일 서버가 디스크에서 읽었다는 증거입니다. 본문은 public/index.html입니다. 백그라운드 서버를 멈추려면 다음과 같이 합니다.

pingclair stop

✅ Pingclair stopped

⚡ 명령 하나로 띄우는 서버

세 하위 명령은 설정 파일 없이 서비스합니다. 시험해 보거나 일회성 호스트에서 유용합니다.

pingclair file-server --listen :8081 --root ./public
pingclair reverse-proxy --from :8082 --to 127.0.0.1:8081
pingclair respond --listen :8083 -s 200 -b "hello from respond"

각각 시작할 때 리스너를 출력합니다.

🚀 Starting file server on :8081 serving ./public (browse: false)
🚀 Starting reverse proxy: :8082 -> ["127.0.0.1:8081"]
Server address: [::]:8083

:8082로 온 요청은 :8081의 파일 서버로 전달되고, :8083은 넘긴 본문을 그대로 돌려줍니다. respond는 개발 전용입니다.

🔁 서비스에 맡기기

서비스는 /etc/Pingclair/Pingclairfile을 실행하므로, 그곳에 두어야 재부팅 후에도 살아남습니다.

sudo cp Pingclairfile /etc/Pingclair/Pingclairfile
sudo pingclair validate /etc/Pingclair/Pingclairfile
sudo pc service reload
curl -i http://localhost/

pc service reload는 실행 중인 서버에 파일을 다시 읽으라고 요청하며, 유닛은 그것을 SIGUSR1로 합니다. pingclair reload는 Admin API를 거쳐 같은 코드에 도달하고 서버가 그 파일을 어떻게 봤는지도 보고합니다(전역 옵션 블록의 admin이 필요합니다). sudo kill -USR1 "$(systemctl show -p MainPID --value pingclair)"는 둘 다 없이 같은 일을 합니다.

어느 쪽이든 먼저 검증하고, 그다음 답을 읽으십시오. systemctl reload가 보고할 수 있는 것은 신호가 전달되었다는 사실뿐이므로, 서버의 판단 — 적용되었는지, 이유와 함께 거부되었는지 — 은 유닛의 status line과 저널에 남습니다. 거부된 재적용은 이전 설정을 계속 서비스합니다. 그것이 거부의 목적입니다. 서비스로 실행에 자세한 설명이 있습니다.

⚠️ 잘 되지 않을 때

Address already in use. 설치 프로그램의 서비스가 아직 :80을 잡고 있거나 다른 프로세스가 그 포트를 잡고 있습니다. sudo ss -ltnp | grep :80이 주인을 보여 주고, sudo pc service stop이 기본 서비스를 풀어 줍니다.
http://localhost:8080에서 Empty reply from server. 평문으로 TLS 리스너에 말하고 있습니다. 사이트 주소에 http://를 붙이거나, 내부 인증서를 신뢰한 뒤 https://로 통신하십시오.
Cannot reach admin API at 127.0.0.1:2019. 설정에 admin이 없어 pingclair stop과 pingclair reload를 받아 줄 대상이 없습니다. 전역 옵션 블록에 추가하거나 포그라운드 프로세스를 Ctrl-C로 멈추십시오.
curl이 루프백에서 멈춤. 시스템 프록시가 요청을 가로채고 있습니다. curl --noproxy '*'로 다시 실행하십시오.
검증이 Unsupported feature로 실패. 지시어는 인식되지만 구현이 없고, 메시지가 대안을 알려 줍니다. encode br의 경우 프록시 응답에 Brotli가 구현되어 있지 않아 encode zstd gzip을 가리킵니다.

🧭 다음 단계

HTTPS: 공개 이름을 위한 인증서를 Let’s Encrypt 또는 내부 인증 기관에서.
서비스로 실행: 유닛, 재적용의 의미, 로그.
Pingclairfile: 언어 자체. 매처, 스니펫, 임포트.

🏃퀵스타트