RESTBase Installation

이 기사의 설정과 조금 다른 설정은 RESTBase/Installation2에서 다룹니다.

Download RESTBase source

데비안에서 RESTBase를 설치하고 설정하는 방법을 다룹니다. 여기서 설치 환경에 대한 정보를 얻을 수 있습니다.

먼저 의존성 프로그램을 설치하고, git 서버에서 소스를 가져와서 RESTBase 서비스에 필요한 프로그램들을 설치합니다.

sudo apt install libsqlite3-dev
mkdir -p ~/git
cd ~/git
git clone https://github.com/wikimedia/restbase.git

최근 1.0.0이 발표되었지만, Parsoid 버전 0.10에서 VisualEditor에서 일부 문제가 발생합니다. 게다가, 웹에서 접근하면, openapi에서 spec을 가져오지 못하는 문제가 있습니다. RESTBase v0.19.3에서 문제없이 동작하기 때문에, 아래와 같이 받을 수 있습니다.

git clone -b v0.19.3 https://github.com/wikimedia/restbase.git

cd restbase
npm install

Configurations

버전 0.19.3

설정에 필요한 파일을 복사합니다.

config.example.yaml config.yaml

설정 파일 config.yaml에서 다음 내용을 수정합니다. Mathoid와 관련된 부분이 없기 때문에 추가하고, 미디어위키 설치와 맞게 일부 수정을 합니다. Parsoid에서 사용한 api.php 경로와 같게 설정이 되어야 합니다.

                - pattern: http://localhost/w/api.php      # 39번째 줄 수정
                    apiUriTemplate: http://localhost/w/api.php  # 51번째 줄 수정
                    baseUriTemplate: "{{'http://{domain}/api/rest_v1'}}" #53번째 줄 수정
                  mathoid:                                    # 54번째 줄 추가  
                    host: http://localhost:10044              # 55번째 줄 추가
                    dbname: /var/lib/restbase/db.sqlite3      # 61번째 줄 수정

위의 설정에서 projects/example.yaml을 참조하므로, 해당 파일에서 mathoid와 events를 추가합니다.

            /media:                                 # 15번째 줄
              x-modules:                            # 16번째 줄
                - path: v1/mathoid.yaml             # 17번째 줄
                  options: '{{options.mathoid}}'    # 18번째 줄
            /mathoid:                               # 58번째 줄
              x-modules:                            # 59번째 줄
                - path: sys/mathoid.js              # 60번째 줄
                  options: '{{options.mathoid}}'    # 61번째 줄
            /events:                                # 85번째 줄
              x-modules:                            # 86번째 줄
                - path: sys/events.js               # 87번째 줄
                  options: '{{merge({"skip_updates": options.skip_updates}, options.events)}}'  # 88번째 줄

위의 example.yaml에서 참조하는 v1/mathoid.yaml파일에서 wikimedia.org를 localhost로 전부 바꿉니다.

마찬가지로, sys/mathoid.js 파일도 수정합니다.

        const uri = '//localhost/api/rest_v1/media/math/';     # 164번째 줄
            uri: new URI(['localhost', 'sys', 'events', '']),  # 173번째 줄

RESTBase 서비스에 대한 새 사용자를 만들고 해당 사용자의 홈 폴더를 만듭니다.

sudo useradd --home=/var/lib/restbase -M --user-group --system --shell=/usr/sbin/nologin -c "RESTBase for MediaWiki" restbase
sudo mkdir -p /var/lib/restbase
sudo chown restbase:restbase /var/lib/restbase
sudo mv ~/git/restbase /usr/local/lib/restbase
sudo chown -R root:root /usr/local/lib/restbase

Systemd 서비스 스크립트 /etc/systemd/system/restbase.service를 다음과 같이 만듭니다:

[Unit]
Description=Mediawiki RESTBase Service
Documentation=https://www.mediawiki.org/wiki/RESTBase
Wants=local-fs.target network.target
After=local-fs.target network.target

[Install]
WantedBy=multi-user.target

[Service]
Type=simple
User=restbase
Group=restbase
WorkingDirectory=/usr/local/lib/restbase
ExecStart=/usr/bin/node /usr/local/lib/restbase/server.js
KillMode=process
Restart=on-success
PrivateTmp=true
StandardOutput=syslog

만약 벡엔드로 카산드라 서비스를 이용하고 있다면, After에 cassandra.server를 추가할 수 있습니다.

서비스를 다시 가져와서 서비스를 시작합니다.

sudo systemctl daemon-reload
sudo systemctl enable restbase
sudo systemctl start restbase
sudo systemctl status restbase

일부 기능이 제대로 작동하려면 외부에서 RESTBase에 액세스할 수 있어야 합니다. 비표준 http 포트에 RESTBase를 설치하면 회사 프록시 또는 방화벽 뒤에 있는 일부 사용자에게 문제가 발생합니다. 이를 해결하고 특별히 HTTP를 통해 RESTBase에 대한 요청을 처리하려면 웹 서버에서 위키의 지정된 경로에 있는 요청을 RESTBase 서버로 라우팅하는 역방향 프록시를 설정해야 합니다. Nginx 설정 파일 /etc/nginx/site-available/default를 다음과 같이 수정합니다.

# 서버 블럭 위에 적습니다.
upstream restbase {
	server localhost:7231;
	keepalive 32;
}

map $request_uri $restbasequery {
        default "xx";
        "~/api/rest_v1/(?<xrestbasequery>.*)$" "$xrestbasequery";
}

# 서버 블럭 안에 적습니다.
	location /api/rest_v1/ {
		proxy_pass http://restbase/localhost/v1/$restbasequery;
	}

Nginx 서비스를 재시작합니다.

sudo systemctl restart nginx

이제 미디어위키 설정 /var/www/html/w/LocalSettings.php을 바꾸고 동작하는지 확인을 합니다:

wfLoadExtension( 'Math' );
$wgMathValidModes[] = 'mathml';
$wgDefaultUserOptions['math'] = 'mathml';
#$wgMathFullRestbaseURL= 'https://en.wikipedia.org/api/rest_'; # 위키피디아의 RESTBase를 사용합니다.
$wgMathFullRestbaseURL= 'http://dawoum.duckdns.org/api/rest_';    # 이렇게 설정해야 동작합니다.

설정을 확인하기 위해서는, http://localhost/api/rest_v1/ 또는 http://dawoum.duckdns.org/api/rest_v1/ 으로 접근했을 때, 위키미디아 REST API가 출력되면, 제대로 동작을 하는 것으로 보입니다.

Mathoid

위에 설정에서 이미 해당 사항을 전부 추가했습니다. 해당 기사로 가셔서 프로그램을 설치하고 서비스를 시작해야 합니다.

Electron Render Service

RESTBase를 통해 Electron 서비스를 하기 위해서, /usr/local/lib/restbase/config.yaml에 다음 설정을 더합니다.

              allow:
                - pattern: http://localhost/w/api.php
                  forward_headers: true
                - pattern: http://localhost:8142
                  forward_headers: true
                - pattern: http://localhost:3000  # 추가
                  forward_headers: true           # 추가
                - pattern: /^https?:\/\//

# 아래쪽으로 내려가셔서 
                  table:
                    backend: sqlite
                    dbname: /var/lib/restbase/db.sqlite3
                    pool_idle_timeout: 20000
                    retry_delay: 250
                    retry_limit: 10
                    show_sql: false
                  purged_cache_control: s-maxage=1209600, max-age=0, must-revalidate
                  purged_cache_control_client_cache: s-maxage=1209600, max-age=300
                  pdf:                                           # 추가
                    cache_control: s-maxage=600, max-age=600     # 추가
                    uri: http://localhost:3000                   # 추가
                    secret: secret                               # 추가
                    scheme: http                                 # 추가

다음 내용을 projects/example.yaml 파일에 더합니다.

                - path: v1/content.yaml
                  options:
                    response_cache_control: '{{options.purged_cache_control}}'
                - path: v1/pdf.js                   # 추가
                  options: '{{options.pdf}}'        # 추가
                - path: v1/common_schemas.yaml

Apache Cassandra

만약 위키미디아 재단 처럼 아파치 카산드라를 설치해서 서비스를 하고 있다면, 테이블에 대한 부분을 다음과 같이 수정해서 사용할 수 있습니다. /usr/local/lib/restbase/config.yaml에서 다음처럼 설정을 수정합니다.

                  table:
                    backend: cassandra
                    hosts: [localhost]
                    keyspace: system
                    username: cassandra
                    password: cassandra
                    defaultConsistency: local_quorum # or 'one' for devel
#                  table:
#                    backend: sqlite
#                    dbname: /var/lib/restbase/db.sqlite3
#                    pool_idle_timeout: 20000
#                    retry_delay: 250
#                    retry_limit: 10
#                    show_sql: false

버전 1.0.0 이후

이제 RESTBase가 가질 기능은 대부분 구현이 되었는지, 처음으로 버전 1.0으로 출시가 되었습니다. 이전 버전에 비해, 설정에서 약간의 변화가 있기 때문에, 그것에 맞게 설정을 바꾸어야 합니다.

먼저, 프로그램의 루트 최상위 디렉토리에는 4개의 설정이 제공됩니다.

config.backend.test.yaml
config.example.yaml
config.frontend.test.yaml
config.fullstack.test.yaml

문서의 설명에는 보통 2번째의 설정을 복사해서 수정하도록 권하고 있지만, 그럴 경우에, 이전에 설정했던 다른 서비스를 별도로 일일이 수정해야 하는 귀찮은 점이 있습니다.

그래서, 이전과 마찬가지로 모든 서비스에 대한 정보가 있는 네 번째 설정을 복사해서 수정하는 것이 좋겠습니다.

sudo cp config.fullstack.test.yaml config.yaml
- 여기서 default_project에서 이전 설정으로부터 서비스를 수정합니다.
- {api:sys}는 default.wmf.yaml 설정을 그대로 사용해도 좋지만, {api:v1}은 자신의 설정으로 바꾸는 것이 좋습니다. table은 backend: cassandra로 바꾸고, dbname: db.sqlite3로 바꿉니다. 그냥 sqlite를 사용하실 분은 example.yaml을 보시고 같은 방법으로 설정하십시오.
- spec_root를 적절히 수정하는데, 모든 도메인은 지워버리고, {domain:localhost} *default_project로 바꿉니다.
- services에서 port는 7231을 사용하도록 수정하고, (꼭 필요한 것은 아니지만) test가 붙은 이름들은 test를 제거해 버립니다.

다음으로, project/v1으로 이동하셔서 별도의 수정을 진행합니다.

cd projects/v1
sudo cp wikipedia.wmf.yaml 위의_설정에서_수정한_이름.yaml
- 위키피디아는 위키미디어의 Mathoid를 사용하므로, 설정에 그 부분이 빠졌습니다. 따라서, wikimedia.wmf.yaml을 보고 mathoid에 관련된 부분을 추가하십시오.
- 그리고 설정을 완료한 후에 오류를 보시고, 필요없는 설정은 제거를 해야 합니다.
- 비록 설명에서 서비스의 목록을 보기 위해 다음 줄을 추가하라고 되어있을지라도, 만약 localhost에서 같이 서비스가 되고 있으면, fetch error가 발생하고, 목록이 보이지 않을 것입니다. 따라서, 아래 줄을 제거하거나, 앞에 (#)을 붙여서 주석처리합니다.
- #x-host-basePath: /api/rest_v1
- 그리고 목록을 볼 때에는 로컬호스트와 포트를 사용한 접근으로 보십시오: http://localhost:7231/localhost/v1/
- 0.19.3에는 이 부분을 주석처리하지 않고도 목록을 볼 수 있었지만, 지금은 왜 그런지 오류가 발생합니다.

이제 서비스의 로컬에서 실행되므로, 나머지에서 필요한 서비스를 로컬로 바꾸어 주어야 합니다. 다음 디렉토리 아래에서 wikimedia.org로 검색 및 wikipedia.org로 검색해서 필요한 부분을 localhost로 바꾸십시오.

특히, 이전 설정처럼, Mathoid에 대한 부분은 반드시 바꾸어 주어야 합니다.

cd ../../sys
cd ../v1

Parsoid

Parsoid가 자바스크립트에서 PHP로 개발을 바꾸면서, 일부 설정이 변경되어야 합니다. Parsoid로 가셔서 변경된 설정을 확인하십시오.

Troubleshootings

서비스 기동 스크립트 : systemd 버전 업그레이드로 syslog 대신 journal을 설정할 수 있습니다. 아니면, 특정 로그 파일을 지정할 수 있습니다.
Node 버전 : 2023년 7월 기준, 아마도 버전 17까지 제대로 작동할 것입니다.

Dawoum

RESTBase Installation

Download RESTBase source

Configurations

버전 0.19.3

Mathoid

Electron Render Service

Apache Cassandra

버전 1.0.0 이후

Parsoid

Troubleshootings

티스토리툴바

RESTBase Installation

Download RESTBase source

Configurations

버전 0.19.3

Mathoid

Electron Render Service

Apache Cassandra

버전 1.0.0 이후

Parsoid

Troubleshootings

관련글

티스토리툴바