deploy-to-connect

Posit Connect へのデプロイ

このガイドでは、Posit Connect サーバー上の Python および R コンテンツについて説明します。各ステージを順番に進めてください。

作業には、次の 2 つのツールチェーンを使用します。

• Python — rsconnect-python。rsconnect CLI を提供し、PyPI で公開されています。
• R — Connect サーバーを指定した R rsconnect パッケージ。

ユーザーがデプロイではなく質問（「どうすれば…」「コマンドは何ですか…」など）をしている場合は、このガイドに基づいて回答し、そこで終了してください。

最後に、デプロイ先のサーバー、選択したコンテンツタイプ、インストールしたツール、および行った仮定を報告してください。

---

ステージ 1 — コンテンツを判別する

プロジェクトディレクトリ内のファイルから、言語とフレームワークを推測します。よくある目印は次のとおりです。

プロジェクトディレクトリ内の目印	考えられるコンテンツ
app.py	Python ウェブアプリ — Shiny for Python、Streamlit、Dash、Gradio、Panel、または Bokeh
app.R、または ui.R + server.R	Shiny for R
plumb() を含む plumber.R / entrypoint.R	Plumber API（R）
*.qmd	Quarto ドキュメント
*.Rmd	R Markdown
*.ipynb	Jupyter ノートブック / Voila
manifest.json	ビルド済みバンドル — フレームワークを推測する必要はなく、そのままデプロイできます
単独の .py または .R — フレームワークのインポートがなく、同じ場所に ui.R / server.R / plumber.R / entrypoint.R もない	スクリプト — Quarto でレンダリングし、Connect でスケジュール実行できるバッチ / ETL ジョブ

推測を確認する

app.py のインポート文からフレームワークを特定できます。

grep -Eo 'import (shiny|streamlit|dash|gradio|panel|bokeh)|from (shiny|streamlit|dash|gradio|panel|bokeh)' app.py

単独の ASGI または WSGI オブジェクトがある場合は、fastapi または flask です。

依存関係ファイルで言語を確認できます。Python の場合は requirements.txt と pyproject.toml、R の場合は DESCRIPTION と renv.lock です。

Quarto でスクリプトをレンダリングするには、先頭にフロントマターコメントが必要です。Python では --- ブロックの前後に # %% [markdown]、R では #' --- を記述します。ほとんどのスクリプトにはありません。デプロイ前に追加してください（ステージ 5）。

コンテンツが曖昧な場合（Python と R の両方のファイルがある場合、または app.py に認識可能なインポートがない場合）は、適宜判断し、行った仮定を報告してください。

---

ステージ 2 — ツールを確認する

環境を調べ、利用可能な機能の一覧を作成します。

command -v rsconnect                                 # rsconnect-python on PATH
command -v uv                                        # uv (installs and runs Python tools)
uv tool list 2>/dev/null | grep rsconnect            # rsconnect-python installed via uv
command -v Rscript                                   # R present
Rscript -e 'cat(requireNamespace("rsconnect", quietly=TRUE))' 2>/dev/null   # R rsconnect package
command -v quarto                                     # quarto CLI
command -v git                                        # git

uv があれば、Python コンテンツのインストール手順は不要です。uv tool run --from rsconnect-python rsconnect ... を実行すると、必要に応じて CLI が取得され、実行されます。

---

ステージ 3 — デプロイ方法を選ぶ

検出したコンテンツ（ステージ 1）と利用可能な機能（ステージ 2）を照合します。

Python コンテンツ

rsconnect-python を使用します。rsconnect が PATH 上にある場合：

rsconnect deploy <framework> ./my-app

PATH 上にはないものの uv がある場合：

uv tool run --from rsconnect-python rsconnect deploy <framework> ./my-app

どちらの形式でも引数は同じです。このガイドでは、以降は rsconnect ... の形式で記載します。2 つ目の方法を使う場合は、先頭に uv tool run --from rsconnect-python を付けてください。

<framework> は api、bokeh、bundle、dash、fastapi、flask、git、gradio、html、manifest、nodejs、notebook、panel、pyproject、quarto、shiny、streamlit、tensorflow、voila のいずれかです。この一覧にないものについては、rsconnect deploy other-content を実行すると手順が表示されます。

フレームワークとフラグはインストールされているバージョンによって異なるため、この一覧ではなく rsconnect deploy --help で確認してください。uv tool run がキャッシュ内の古いバージョンを解決する場合は、uv tool run --from 'rsconnect-python==1.30.0' rsconnect ... のようにバージョンを固定してください。

R コンテンツ

R の rsconnect パッケージを、Rscript -e '...' または R セッションから使用します。

• Shiny for R、Plumber API、または任意のアプリディレクトリ → deployApp()
• 単一の R Markdown または Quarto ドキュメント → deployDoc()
• 完全な R Markdown または Quarto サイト → deploySite()

Rscript がない場合は、manifest.json を使って rsconnect-python 経由で R コンテンツをデプロイします。

• manifest.json がすでにある場合は、そのままデプロイします。

  rsconnect deploy manifest ./manifest.json
  

• マニフェストはないものの、別の環境で R を使用できる場合は、まず rsconnect::writeManifest() で生成します（ステージ 5 を参照）。
• R もマニフェストもない場合は、有効な R バンドルを作成できません。これをブロッカーとして示し、ユーザーに確認するか、明確に報告してください。

Quarto コンテンツ

rsconnect deploy quarto ./report

R コードチャンクを含む R 形式の Quarto（.qmd）をレンダリングするには、R が必要です。R がない場合は、そのドキュメントを R コンテンツとして扱い、マニフェスト経由の方法を使うか、不足していることを伝えてください。

スクリプトコンテンツ

quarto フレームワークを使用します。まずフロントマターを追加します（ステージ 5）。

rsconnect deploy quarto script.py    # Python, rsconnect-python 1.23.0 or later

rsconnect::deployApp()               # R, rsconnect 1.2.2 or later, from the directory of the script

どちらのコマンドも、ディレクトリ内のすべてのファイルを含めます。ボタン操作による公開は R スクリプトに対応していないため、R での方法は deployApp() のみです。

スクリプトのデプロイ方法は Quarto ドキュメントと同じですが、コンテンツの種類は異なります。.qmd は読むためのページであり、スクリプトは出力を書き出すジョブです。

---

ステージ 4 — デプロイ先を特定し、認証情報を確認する

ツールがわかったら、どのサーバーにデプロイするか、そのツールからすでに接続できるかを確認します。これは確認であり、ログインではありません。

API キーを探すために環境を検索しないでください。 デプロイ先の選定やサーバーの登録のために、CONNECT_API_KEY、CONNECT_SERVER、.env ファイル、キーチェーンのエントリ、その他の保存されたシークレットを読み取らないでください。ユーザーから明示的に求められた場合に限り、これを行ってください。環境変数があることは、それを使用するよう求められていることを意味しません。

ツールにすでに登録されているアカウントを一覧表示します。必要な認証情報の確認はこれだけです。

rsconnect list                                   # Python: saved servers, stored tokens, and the default server on 1.30.0+
Rscript -e 'print(rsconnect::accounts())'        # R: registered accounts

まだツールがインストールされていない場合は、まずステージ 5 でその不足を解消してください。その後、確認を実行します。

結果を、ユーザーが指定したデプロイ先と照合します。結果は 3 通りあります。

• アカウントが指定されたデプロイ先と一致する。 認証情報は使用可能です。ログインも rsconnect add も実行しないでください。ほかの不足が解消されたら、ステージ 6 に進みます。
• ユーザーがデプロイ先を指定していない。 ユーザーに尋ねてください。確認で見つかったサーバーを一覧表示し、どれにデプロイするか、または新しいデプロイ先を使うかを尋ねてください。代わりに選んだり、保存されているサーバーが 1 つしかないという理由でそこにデプロイしたりしないでください。
• デプロイ先が新しい、または一致するアカウントがない。 これはステージ 5 で解消すべき不足です。ブラウザーからログインして登録します。

新しいデプロイ先を登録するには、ブラウザーからログインします。

rsconnect login https://connect.example.com      # Python

rsconnect::addServer(url = "https://connect.example.com", name = "myserver")   # R
rsconnect::connectUser(server = "myserver")

どちらの形式でもブラウザーのフローが開くため、ユーザーがログインを承認し、キーが会話を経由することはありません。詳細と注意点については、認証情報のリファレンスを参照してください。

---

Stage 5 — 不足を解消する

Stage 3 と Stage 4 で不足が見つかった場合は解消し、その対応をレポートに記載します。

rsconnect が PATH にありません。 uv があれば、インストールは不要です。

uv tool run --from rsconnect-python rsconnect deploy <framework> ./my-app

ユーザーが永続的なインストールを希望する場合、または uv tool run が利用できない場合：

uv tool install rsconnect-python     # or: pip install rsconnect-python

パッケージ名とコマンド名は異なります。PyPI パッケージは rsconnect-python で、提供されるコマンドは rsconnect です。そのため、uv tool run には --from rsconnect-python が必要です。後でアップグレードするには、uv tool upgrade rsconnect-python を実行します。

R の rsconnect パッケージがなく、Rscript はあります。 コンパイル済み Linux バイナリを提供する Posit Package Manager（P3M）からインストールします。バイナリのインストールはソースからのビルドよりはるかに高速で、-dev システムライブラリも不要です。バイナリの利用には、__linux__/<codename> リポジトリ URL と、プラットフォームを識別する HTTPUserAgent の 2 つが必要です。ユーザーエージェントがない場合、P3M はソースを提供します。

export P3M="https://packagemanager.posit.co/cran/__linux__/$(. /etc/os-release && echo "$VERSION_CODENAME")/latest"
Rscript -e '
  options(HTTPUserAgent = sprintf("R/%s R (%s)", getRversion(),
    paste(getRversion(), R.version["platform"], R.version["arch"], R.version["os"])))
  install.packages("rsconnect", repos = Sys.getenv("P3M"))
'

P3M バイナリは、一般的なディストリビューションの x86_64 向けに用意されています。arm64 またはサポートされていないディストリビューションでは、P3M はソースにフォールバックします。その場合も動作に問題はありませんが、時間がかかり、通常の -dev ライブラリとコンパイラーが必要です。P3M に到達できない場合に限り、https://cloud.r-project.org（CRAN ソース）を使用します。

R のコンテンツに manifest.json がなく、R はあります。 生成します。

Rscript -e 'rsconnect::writeManifest()'

rsconnect-python は Python のコンテンツ用にマニフェストを書き込みます。

rsconnect write-manifest <framework> ./my-app

その後、R から直接デプロイできない場合は、rsconnect-python でマニフェストをデプロイします。

スクリプトのフロントマターがありません。 ファイルの先頭に最小限のブロックを追加します。Connect は title からコンテンツのタイトルを取得するため、内容が伝わるタイトルを記述します。

Python：

# %% [markdown]
# ---
# title: "Data processing script"
# ---

R：

#' ---
#' title: "Data processing script"
#' ---

対象のアカウントがありません。 ブラウザーログインで今すぐ登録します。Python の場合は rsconnect login、R の場合は rsconnect::addServer() と rsconnect::connectUser() を使用します。詳細と注意点は認証情報のリファレンスを参照してください。環境変数にある API キーで代用しないでください。ブラウザーフローを利用できない場合は、その旨を報告して終了します。

依存関係。 rsconnect と rsconnect-python はコードをスキャンして必要なパッケージのバージョンをスナップショットするため、手作業で一覧にする必要はほとんどありません。Python コンテンツには requirements.txt が必要です。R の場合、rsconnect が検出できるよう、コンテンツで使用するパッケージをローカルにインストールしておく必要があります。Plumber API には plumber、Shiny アプリには shiny が必要です。不足しているものは、上記と同じ P3M リポジトリからインストールします。

---

Stage 6 — デプロイして失敗に対処する

現在のコマンド体系を確認する（Python）

rsconnect-python のフレームワークとフラグはリリースごとに変わるため、ヘルプテキストを正とします。

rsconnect version                  # which version you are actually running
rsconnect deploy --help            # every framework you can deploy
rsconnect deploy <framework> --help  # flags for one framework

デプロイする

Python の場合は、Stage 3 で選んだフレームワークを使って rsconnect deploy <framework> <dir> を実行します。manifest フレームワークでは、ディレクトリではなくマニフェストファイルを指定します。

見落としやすいフラグ：-t/--title、-N/--new（記録済みのデプロイを更新する代わりに新規デプロイを強制）、-a/--app-id <id>（既存のアイテムを明示的に対象にする。--new とは併用不可）、-E NAME=VALUE（環境変数を設定。繰り返し指定可能）、--draft（公開されるまで以前のバンドルを引き続き提供）。

R の場合は、Stage 3 で選んだ関数を呼び出します。コンテンツ名がディレクトリ名にならないよう、appTitle を渡します。

スクリプトのデプロイでは、ディレクトリ全体が対象になります。ディレクトリにスクリプトで必要としないファイルがある場合は、対象を絞ります。Python ではファイル名を指定し（rsconnect deploy quarto script.py helper.py data.csv）、R では appFiles を渡します（rsconnect::deployApp(appFiles = c("_quarto.yml", "script.R"))）。_quarto.yml があるディレクトリは Quarto プロジェクトです。rsconnect deploy quarto . で全体をデプロイします。

デプロイ時に rsconnect が見つからない場合

インストールされていても、このシェルの PATH にない可能性があります。IDE が起動したターミナルと有効な virtualenv は、どちらもこの状況の原因になります。Stage 5 の説明に従い、--from rsconnect-python を指定して uv tool run に切り替えます。

事前確認（任意）

デプロイ前に、対象に接続でき、認証情報が有効であることを確認するには：

rsconnect details -n myserver

デプロイに失敗した場合

Python：

• 認証エラー — rsconnect list で対象を確認し、rsconnect login を再実行します（1.30.0+）。-s/-k を渡すのは、既存のキーを使うようユーザーから指示された場合に限ります。
• -n/--name ... cannot be specified in conjunction with ... -s/--server (from ENVIRONMENT) — CONNECT_SERVER が設定されており、さらに -n も渡しています。unset CONNECT_SERVER を実行し、-n はそのまま使います。認証情報のリファレンスで、この指定方法が必要な理由を説明しています。CONNECT_API_KEY はそのまま設定しておけます。
• The requirements file 'requirements.txt' does not exist — Python のコンテンツにはこのファイルが必要です。作成するか、--requirements-file で別のファイルを指定するか、--force-generate で生成します。最後の方法では pip freeze が実行されるため、依存関係のバージョンが細かく固定されすぎる場合があります。
• 自己署名 TLS — -i/--insecure または -c/--cacert <file> を使用します。すべての処理に適用するには、CONNECT_INSECURE または CONNECT_CA_CERTIFICATE を設定します。
• フラグが拒否される、またはフレームワークが不明と表示される — rsconnect version を再確認し、rsconnect deploy <framework> --help を読み直します。通常、インストール済みのバージョンが、使用したフラグに対応するバージョンより古いことが原因です。
• デプロイしたスクリプトが空、または正しく表示されない — サーバーに Quarto 1.4+、Jupyter（Python スクリプトの場合）、または rmarkdown（R スクリプトの場合）がありません。デプロイ自体は成功しているため、再試行しないでください。不足しているサーバー側の依存関係を報告します。

R：

• 「アカウントがない」または認証エラー — rsconnect::accounts() を実行します。結果が空の場合は、rsconnect::addServer() を再実行してから、connectUser() または connectApiUser() を実行します。connectCloudUser() ではなく、サーバー用の関数を使用したことを確認します。
• Found multiple accounts. Please disambiguate by setting server and/or account — 複数のアカウントがリンクされています。デプロイ呼び出しに account = と server = を明示的に渡します。対話型 R セッションでは代わりにメニューが表示され、ヘッドレス実行が停止します。
• デプロイ関数の指定が誤っている — ディレクトリとアプリには deployApp()、単一のドキュメントには deployDoc()、サイトには deploySite() を使います。
• 自己署名 TLS — CA バンドルを curl オプションで渡すか、証明書を指定してサーバーを追加します。簡単にテストするには、options(rsconnect.check.certificate = FALSE) を設定します。
• 絶対パスの警告 — 絶対パスがハードコードされたファイルがあっても、デプロイは妨げられません。ただし、プロジェクトディレクトリを基準とする相対パスにすることをおすすめします。

---

認証情報のリファレンス

ステージ 4 でアカウントが見つからなかった対象を登録する方法です。対象に一致するアカウントがすでにある場合は、以下の操作は必要ありません。

ブラウザーでログインする方法を使います。その下に記載した API キーを使う方法は、既存のキーを使うようユーザーから明示的に指示された場合に限ります。キーは、環境変数または認証情報ストアに保存されているものです。自分でキーを探してはいけません。また、ユーザーにキーを教えるよう求めてはいけません。API キーを会話に含めてはいけません。

Python (rsconnect-python)

1. OAuth ログイン（対話式）。 デフォルトの方法です。rsconnect-python 1.30.0 以降が必要なので、まず rsconnect version を確認してください。サーバーごとにブラウザーでの認証フローを 1 回実行します。トークンは OS のキーリングまたはローカルの認証情報ストアに保存され、自動的に更新されます。

   rsconnect login https://connect.example.com
   rsconnect login https://connect.example.com --use-device-code   # headless
   

2. 保存済み API キーのニックネーム。 ユーザーがキーを使う方法を希望した場合に限ります。一度保存し、以降は -n/--name で選択します。

   rsconnect add -n myserver -s https://connect.example.com -k <api-key>
   rsconnect list                    # confirm what is saved
   

   1.30.0 以降では、サーバーをデフォルトに設定できます。コマンドに -n も -s も指定されていない場合に使用されます。add は --set-default を指定した場合にのみデフォルトを設定します。login は --no-set-default を指定しない限り、デフォルトを設定します。後から rsconnect server set-default -n <name> で変更できます。CONNECT_SERVER は引き続きデフォルトより優先されます。
3. 環境変数。 ユーザーが環境変数の使用を希望した場合に限ります。rsconnect-python は環境変数を直接読み取るため、状態管理が不要なヘッドレス実行や自動実行に適しています。

   export CONNECT_SERVER=https://connect.example.com
   export CONNECT_API_KEY=...        # honored across the whole `rsconnect` surface
   

4. デプロイコマンドのその場限りのフラグ：-s <url> -k <api-key>。同じ条件で使用し、キーはユーザーが指定した変数から読み取り、値を直接書き出さないでください。

共通の認証情報フラグ：-n/--name（保存済みサーバー）、-s/--server（環境変数 CONNECT_SERVER）、-k/--api-key（環境変数 CONNECT_API_KEY）、-i/--insecure（自己署名 TLS 用の環境変数 CONNECT_INSECURE）、-c/--cacert <file>（環境変数 CONNECT_CA_CERTIFICATE）。

-n と CONNECT_SERVER は同時に指定できません。保存済みサーバー名（-n/--name）とサーバー URL を組み合わせたコマンドは rsconnect に拒否されます。環境変数から取得した URL も同様です：-n/--name (from COMMANDLINE) cannot be specified in conjunction with options -s/--server (from ENVIRONMENT)。

競合するのはサーバーだけです。キーは除外対象ではないため、CONNECT_API_KEY、CONNECT_INSECURE、CONNECT_CA_CERTIFICATE は -n と併用しても問題ありません。CONNECT_API_KEY を設定した状態での -n dogfood は有効なコマンドです。解除が必要なのは CONNECT_SERVER です。

設定されている環境変数ではなく、リクエストで指定された内容に基づいて選択してください。

• リクエストで保存済みサーバーが指定されている（「dogfood にデプロイして」）場合 — -n dogfood を使い、そのコマンドでは unset CONNECT_SERVER を実行してください。逆の方法で競合を解消するのは望ましくありません。CONNECT_SERVER がまったく別のサーバーを指している可能性があるため、これを残して -n を省くと、ユーザーが指定していないサーバーにデプロイしてしまうおそれがあります。
• リクエストでサーバーが指定されていない場合（一般的なヘッドレス実行）— CONNECT_SERVER と CONNECT_API_KEY で接続先を指定し、rsconnect deploy <framework> <dir> でデプロイしてください。

CONNECT_SERVER はシークレットではありません。どのサーバーを指しているか不明な場合は表示し、デプロイ先のサーバー名を報告してください。

R (rsconnect)

サーバーをローカルのニックネームで登録してから、そのサーバーに対してユーザーを登録します。

library(rsconnect)

# 1. The server (once per server; the name is a local nickname)
rsconnect::addServer(url = "https://connect.example.com", name = "myserver")

# 2a. Interactive — approve in a browser, no key to handle
rsconnect::connectUser(server = "myserver")

# 2b. Or non-interactively (CI), only when the user asked for a key route
rsconnect::connectApiUser(
  server  = "myserver",
  account = "your-username",
  apiKey  = Sys.getenv("CONNECT_API_KEY")
)

connectCloudUser() は Connect Cloud（別のサービス）に対して認証するため、Connect サーバーでは動作しません。ここでは connectUser() または connectApiUser() を使用してください。

ログイン方法を利用できない場合

その旨を報告して停止してください。登録を試みたサーバー名と、失敗したログインコマンドを伝えてください。不足を補うために、環境変数、.env ファイル、認証情報ストアからキーを探してはいけません。また、ユーザーにキーを尋ねてもいけません。次の手順はユーザーに判断してもらいます。