Ubuntu24.04LTSにDockerで動作するOpenCodeをインストールする手順

Posted at 2026-07-14

この記事は、LinuxやDockerの操作が初めての方を対象に、Ubuntu 24.04 LTS環境へのDockerのインストールから、AI搭載の自律型開発エージェント「OpenCode（opencode-ai）」のコンテナ環境構築、そして実際の動作検証までをステップ・バイ・ステップで解説する手順書です。

各コマンドの意味や、初心者が躓きやすいポイント（権限エラーなど）についても丁寧に解説しています。

1. 全体の作業フロー

本マニュアルでは、以下の4つのステップ順に作業を進めます。

ホストOS（Ubuntu）へのDockerインストールの準備と実行
OpenCode専用のDockerイメージと設定ファイルの作成
Dockerコンテナのビルドと起動
OpenCodeエージェントの起動と自律開発タスクの動作検証

2. 【Step 1】Dockerのインストール

Dockerは、アプリケーションを「コンテナ」と呼ばれる独立した環境で実行するためのプラットフォームです。まずはUbuntu 24.04に公式の最新版Dockerをインストールします。

2.1. システムパッケージの更新と必須ツールの導入

端末（ターミナル）を開き、以下のコマンドを一行ずつ実行してください。

# 1. パッケージリストを最新の状態に更新します
sudo apt-get update

# 2. セキュリティ通信や鍵管理に必要な基本ツールをインストールします
sudo apt-get install -y ca-certificates curl gpg

💡 初心者向けヒント: sudo で始まるコマンドを実行するとパスワードを求められます。Ubuntuのログインパスワードを入力してください（入力中の文字は画面に表示されませんが、そのまま入力してエンターキーを押せば進みます）。

2.2. Docker公式GPG鍵の追加

安全にパッケージをダウンロードするために、Docker公式の暗号鍵（GPG鍵）をシステムに登録します。

# 鍵を保存するディレクトリを作成し、適切な権限（0755）を設定します
sudo install -m 0755 -d /etc/apt/keyrings

# Docker公式のGPG鍵をダウンロードして保存します
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor --yes -o /etc/apt/keyrings/docker.gpg

# すべてのユーザーがこの鍵を読み込めるように権限を変更します
sudo chmod a+r /etc/apt/keyrings/docker.gpg

2.3. Docker公式リポジトリの登録

Ubuntuの標準リポジトリではなく、常に最新版が提供されるDocker公式のリポジトリを参照するように設定します。

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

2.4. Dockerエンジンのインストール

リポジトリの登録が完了したら、パッケージリストを再更新してインストールを行います。

# リポジトリを追加したため、再度パッケージリストを更新します
sudo apt-get update

# Docker本体、CLIツール、コンテナ管理システム（containerd）、各種プラグインをまとめてインストールします
sudo apt-get install -y \
  docker-ce \
  docker-ce-cli \
  containerd.io \
  docker-buildx-plugin \
  docker-compose-plugin

2.5. Dockerサービスの起動と自動起動設定

システム起動時にDockerが自動で立ち上がるように設定します。

sudo systemctl enable --now docker

2.6. 一般ユーザーでDockerを操作するための設定（重要）

初期状態では、Dockerコマンドを実行するたびに sudo（管理者権限）が必要です。毎回 sudo を付けなくて済むよう、現在ログインしているユーザーを docker グループに加入させます。

# dockerグループを作成します（既に存在する場合はスキップされます）
sudo groupadd docker

# 現在のログインユーザー（$USER）をdockerグループに追加します
sudo usermod -aG docker "$USER"

⚠️ 注意（必ず実施してください）: このグループ設定をシステムに反映させるため、一度Ubuntuからログアウトし、再ログイン（可能なら再起動を推奨します）を行ってください。

2.7. インストール成功の確認

再ログイン後、端末を開いて以下の3つのコマンドを実行し、正常に動作するか確認します。

# バージョンが表示されることを確認
docker --version

# Docker Composeのバージョンが表示されることを確認
docker compose version

# テスト用コンテナを実行し、「Hello from Docker!」と表示されれば成功です
docker run hello-world

3. 【Step 2】OpenCode用Docker環境の構築

OpenCodeをホストOS（Ubuntu）に直接インストールするのではなく、Dockerコンテナ内に隔離して構築します。これにより、ホスト環境を汚さずに日本語環境やNode.js、Python環境が整った強力なAIエージェント環境を手に入れることができます。

3.1. 事前準備：作業ディレクトリの作成

本マニュアルでは、以下のディレクトリ構成を作成して作業を進めます。

設定ファイル配置先: /home/foo/work/ws-docker-opencode
OpenCodeの成果物出力先: /home/foo/work/ws-docker-opencode/workspace01

以下のコマンドを実行して、フォルダを準備します。

mkdir -p /home/foo/work/ws-docker-opencode/workspace01
cd /home/foo/work/ws-docker-opencode

💡 ユーザー名に関する注意: 上記のパスに含まれる foo はサンプルです。ご自身のユーザー名に合わせて適宜読み替えてください（例: mkdir -p ~/work/ws-docker-opencode/workspace01 のようにホームディレクトリ記号 ~ を使うと確実です）。

3.2. Dockerfileの作成

Dockerfile は、コンテナの「設計図」です。Ubuntu 24.04をベースに、日本語ロケール、Node.js 22、JDK 21、Python3、そしてOpenCodeを自動インストールする設定を記述します。

現在の作業ディレクトリ（/home/foo/work/ws-docker-opencode）に Dockerfile という名前のファイルを作成し、以下の内容を記述して保存してください（VimやGeditなどのテキストエディタを使用します）。

# 設計図のベースとしてUbuntu 24.04を使用
FROM ubuntu:24.04

# インストール中の対話プロンプトを非表示にする設定
ENV DEBIAN_FRONTEND=noninteractive

# タイムゾーンを日本時間に設定
ENV TZ=Asia/Tokyo

# 基本的な開発ツール・ユーティリティ・ランタイム（Java/Python含む）のインストール
RUN apt-get update && \
    apt-get install -y \
        locales \
        tzdata \
        curl \
        wget \
        git \
        ca-certificates \
        unzip \
        zip \
        less \
        vim \
        nano \
        ripgrep \
        fd-find \
        jq \
        tree \
        build-essential \
        python3 \
        python3-pip \
        openjdk-21-jdk \
    && rm -rf /var/lib/apt/lists/*

# 日本語ロケール（文字化け対策）の生成と設定
RUN sed -i 's/^# *ja_JP.UTF-8 UTF-8/ja_JP.UTF-8 UTF-8/' /etc/locale.gen && \
    locale-gen

ENV LANG=ja_JP.UTF-8
ENV LANGUAGE=ja_JP:ja
ENV LC_ALL=ja_JP.UTF-8

# Node.js 22 LTSの公式リポジトリ追加とインストール
RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && \
    apt-get update && \
    apt-get install -y nodejs && \
    rm -rf /var/lib/apt/lists/*

# OpenCode (opencode-ai) をグローバルインストール
RUN npm install -g opencode-ai

# コンテナ起動時の初期作業ディレクトリを設定
WORKDIR /workspace

# Gitで日本語ファイル名がエスケープ（文字化け）されるのを防ぐ設定
RUN git config --system core.quotepath false

# 起動時はbashシェルを実行
CMD ["bash"]

3.3. docker-compose.ymlの作成

docker-compose.yml は、コンテナの起動オプション（マウント位置、環境変数、ネットワーク設定など）を効率的に管理するための設定ファイルです。

同じディレクトリに docker-compose.yml という名前のファイルを作成し、以下の内容を保存してください。

version: '3.8'

services:
  opencode:
    # カレントディレクトリにあるDockerfileを使用してビルド
    build:
      context: .

    # 生成されるイメージ名
    image: opencode:latest

    # 起動するコンテナ名
    container_name: opencode

    # ホストOSのユーザーID/グループIDをコンテナに引き継ぎ、ファイルの権限問題を防止
    user: "${UID}:${GID}"

    working_dir: /workspace

    # ホストOSのディレクトリをコンテナ内の /workspace に同期（マウント）
    volumes:
      - /home/foo/work/ws-docker-opencode/workspace01:/workspace

    # コンテナをバックグラウンドで維持するための設定
    stdin_open: true
    tty: true
    init: true

    # コンテナ内部の環境変数（日本語化とタイムゾーン）
    environment:
      HOME: /tmp
      TZ: Asia/Tokyo
      LANG: ja_JP.UTF-8
      LANGUAGE: ja_JP:ja
      LC_ALL: ja_JP.UTF-8

    # コンテナ内からホストOS自体（Local LLMサーバー等）にアクセス可能にするためのホスト名登録
    extra_hosts:
      - "host.docker.internal:host-gateway"

⚠️ 注意: volumes: の左側のパス（/home/foo/work/ws-docker-opencode/workspace01）は、ご自身の実環境の絶対パスに書き換えてください。

3.4. Dockerコンテナのビルドとバックグラウンド起動

設定ファイルの配置が終わったら、以下のコマンドを実行してコンテナを構築・起動します。

# 1. Dockerfileを基にイメージをビルドします（初回は数分かかります）
docker compose build

# 2. コンテナをバックグラウンドで起動（-d）します
docker compose up -d

正しく起動したか確認するには、docker compose ps を実行し、opencode コンテナの状態が running (または Up) になっていることを確認してください。

4. 【Step 3】OpenCodeの動作検証

コンテナが無事に起動したら、コンテナの内部に入り、OpenCode AIエージェントに自律的なプログラミングタスクを指示して、正常に動作するか検証します。

4.1. 起動中のコンテナへ接続

以下のコマンドを実行して、起動している opencode コンテナ内部のbashシェルにログインします。

docker exec -it opencode bash

実行後、プロンプトの表示が変わり、コンテナ内の /workspace ディレクトリにいる状態になります。

4.2. OpenCodeの起動

コンテナ内で以下のコマンド入力をすると、OpenCodeのインタラクティブモード（対話型AIインターフェース）が起動します。

opencode

💡 補足: 必要に応じて、OpenCodeが裏側で利用する大規模言語モデル（LLM）への接続・APIキー設定画面などが表示される場合があります。ローカルLLMを使用する場合は、ホストOS側で Ollama などを起動しておき、http://host.docker.internal:11434 を指定して連携させます。

4.3. AIエージェントへのタスク指示（テスト実行）

OpenCodeのプロンプト（指示入力画面）が表示されたら、以下のテキストをコピー＆ペーストしてエンターキーを押してください。

パッケージ管理ツールuvを使用して、プロジェクト "sample01"を作成し、"sample01プロジェクト"内で、pythonで"エラトステネスのふるい"を作成して、作成後は実行テストをしてください。

OpenCodeは指示を受けると、人間が介入することなく自律的に以下のステップを実行します：

高速なPythonパッケージ管理ツール uv がシステムにあるか確認（なければ導入を検討、またはプロジェクト初期化を試行）
uv init sample01 に相当するコマンドを自律実行し、プロジェクト構造を自動生成
素数を特定するアルゴリズムである「エラトステネスのふるい」を実装した main.py を自動記述
コンテナ内のターミナルを自律的に操作し、プログラムが正常に動作するかテスト実行を敢行

4.4. ホスト側での成果物確認（検証完了）

OpenCodeが「タスク完了」を報告したら、一度コンテナから抜ける（exit コマンドを入力するか、新しくホスト側のUbuntuで別の端末を開く）などして、ホストOS側のマウント先ディレクトリを確認します。

ホストOS側で以下のコマンドを実行します。

cd /home/foo/work/ws-docker-opencode/workspace01
tree sample01/

以下のようなディレクトリ構成とファイル群が自動生成されていれば、Ubuntu 24.04で Docker + OpenCode の構築および動作検証はすべて成功です。

sample01/
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

1 directory, 4 files

各ファイル（main.pyなど）を開くと、AIが記述したソースコードや、uv によって厳密にロックされた依存関係ファイルが確認できます。お疲れ様でした！

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up