Skip to content

Set up local development with the Oracle Autonomous AI Database Free Container Image

Jump to bottom
Abhishek Singh edited this page Apr 27, 2026 · 3 revisions

This setup is aimed at developers who want a fast local environment for python-select-ai development, demos, and workshop-style testing.

Why this setup is useful:

  • It is excellent for local development and demos.
  • You can run the Oracle Autonomous AI Database Free Container Image on your laptop.
  • You can wire it up to python-select-ai in a few minutes.
  • You get a repeatable, disposable environment without waiting on shared infrastructure.

Table of Contents

Requirements

  • adb-free: Oracle Autonomous AI Database Free Container Image
  • python-select-ai: Python SDK for Select AI

Have these installed first:

  • podman or docker
  • Python 3.10+

If you are on macOS or Windows and use Podman, initialize a Linux VM first:

podman machine init
podman machine set --cpus 4 --memory 8192
podman machine start

Setup

1. Create a local working folder

mkdir -p "$HOME/adb-free-select-ai-demo"
cd "$HOME/adb-free-select-ai-demo"

2. Set passwords

Use your own strong values.

export ADB_ADMIN_PASSWORD='Welcome_123456'
export ADB_WALLET_PASSWORD='Wallet_123456'

3. Start the Oracle Autonomous AI Database Free Container Image

This is the quickest option for local development with python-select-ai:

podman run -d \
  -p 1521:1522 \
  -p 1522:1522 \
  -p 8443:8443 \
  -p 27017:27017 \
  -e WORKLOAD_TYPE=ATP \
  -e ADMIN_PASSWORD="$ADB_ADMIN_PASSWORD" \
  -e WALLET_PASSWORD="$ADB_WALLET_PASSWORD" \
  --cap-add SYS_ADMIN \
  --device /dev/fuse \
  --name adb-free \
  ghcr.io/oracle/adb-free:latest-26ai

If you prefer Docker, use the same command with docker run instead of podman run.

4. Wait for the container to be healthy

podman wait --condition=healthy adb-free

If you want to inspect startup logs while troubleshooting, run:

podman logs -f adb-free

5. Copy the wallet to your host

mkdir -p "$PWD/wallet"
podman cp adb-free:/u01/app/oracle/wallets/tls_wallet/. "$PWD/wallet"
export TNS_ADMIN="$PWD/wallet"

If you prefer, this directory can be any path such as /scratch/tls_wallet. In this guide, $PWD/wallet is used so the whole setup stays self-contained.

6. Create and activate a Python virtual environment

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install select_ai

7. Set connection variables

Set DB_DSN to a service name from your wallet's tnsnames.ora. Example: myatp_medium.

export DB_USER='admin'
export DB_PASSWORD="$ADB_ADMIN_PASSWORD"
export DB_DSN='myatp_medium'
export WALLET_LOCATION="$PWD/wallet"
export WALLET_PASSWORD="$ADB_WALLET_PASSWORD"
export TNS_ADMIN="$WALLET_LOCATION"

These wallet-related variables are important for python-select-ai when connecting to the local adb-free instance.

If you keep the wallet under /scratch/tls_wallet, set:

export WALLET_LOCATION=/scratch/tls_wallet
export WALLET_PASSWORD="$ADB_WALLET_PASSWORD"
export TNS_ADMIN=/scratch/tls_wallet

Verify SQL*Plus connectivity

If sqlplus is installed, run:

sqlplus "$DB_USER/$DB_PASSWORD@$DB_DSN"

Then verify the connection:

select sysdate from dual;

Verify Python select_ai connectivity

Run this to verify your local database, wallet, and python-select-ai are wired correctly.

cat > select_ai_connect_test.py <<'PY'
import os
import ssl
from pathlib import Path

import select_ai

wallet_dir = Path(os.environ["TNS_ADMIN"])
ssl_context = ssl.create_default_context(cafile=str(wallet_dir / "adb_container.cert"))
if hasattr(ssl, "VERIFY_X509_STRICT"):
    ssl_context.verify_flags &= ~ssl.VERIFY_X509_STRICT

select_ai.connect(
    user=os.environ["DB_USER"],
    password=os.environ["DB_PASSWORD"],
    dsn=os.environ["DB_DSN"],
    wallet_location=os.environ["TNS_ADMIN"],
    wallet_password=os.environ["WALLET_PASSWORD"],
    ssl_server_dn_match=False,
    ssl_context=ssl_context,
)

print("python-select-ai connected successfully")
PY

python select_ai_connect_test.py

Expected output:

python-select-ai connected successfully

8. Create a Select AI profile

Use Database Actions or SQL*Plus and run this example. It creates a credential, creates a profile, and points it at OpenAI. Replace the API key with your own value.

BEGIN
  DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
    host => 'api.openai.com',
    ace  => xs$ace_type(
      privilege_list => xs$name_list('http'),
      principal_name => 'ADMIN',
      principal_type => xs_acl.ptype_db
    )
  );
END;
/

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'OPENAI_CRED',
    username        => 'OPENAI',
    password        => '<your-openai-api-key>'
  );
END;
/

BEGIN
  DBMS_CLOUD_AI.CREATE_PROFILE(
    profile_name => 'OPENAI',
    attributes   => '{"provider":"openai","credential_name":"OPENAI_CRED"}'
  );
END;
/

Equivalent Python select_ai API:

cat > create_select_ai_profile.py <<'PY'
import os
import ssl
from pathlib import Path

import select_ai

wallet_dir = Path(os.environ["TNS_ADMIN"])
ssl_context = ssl.create_default_context(cafile=str(wallet_dir / "adb_container.cert"))
if hasattr(ssl, "VERIFY_X509_STRICT"):
    ssl_context.verify_flags &= ~ssl.VERIFY_X509_STRICT

select_ai.connect(
    user=os.environ["DB_USER"],
    password=os.environ["DB_PASSWORD"],
    dsn=os.environ["DB_DSN"],
    wallet_location=os.environ["TNS_ADMIN"],
    wallet_password=os.environ["WALLET_PASSWORD"],
    ssl_server_dn_match=False,
    ssl_context=ssl_context,
)

select_ai.grant_http_access(
    users=os.environ["DB_USER"],
    provider_endpoint="api.openai.com",
)

select_ai.create_credential(
    credential={
        "credential_name": "OPENAI_CRED",
        "username": "openai",
        "password": os.environ["OPENAI_API_KEY"],
    },
    replace=True,
)

provider = select_ai.OpenAIProvider()
profile_attributes = select_ai.ProfileAttributes(
    credential_name="OPENAI_CRED",
    provider=provider,
)

profile = select_ai.Profile(
    profile_name="OPENAI",
    attributes=profile_attributes,
    description="OpenAI profile",
    replace=True,
)

print(f"Created profile: {profile.profile_name}")
PY

export OPENAI_API_KEY='<your-openai-api-key>'
python create_select_ai_profile.py

9. Test a prompt with the profile

export SELECT_AI_PROFILE='OPENAI'
cat > select_ai_profile_test.py <<'PY'
import os
import ssl
from pathlib import Path

import select_ai

wallet_dir = Path(os.environ["TNS_ADMIN"])
ssl_context = ssl.create_default_context(cafile=str(wallet_dir / "adb_container.cert"))
if hasattr(ssl, "VERIFY_X509_STRICT"):
    ssl_context.verify_flags &= ~ssl.VERIFY_X509_STRICT

select_ai.connect(
    user=os.environ["DB_USER"],
    password=os.environ["DB_PASSWORD"],
    dsn=os.environ["DB_DSN"],
    wallet_location=os.environ["TNS_ADMIN"],
    wallet_password=os.environ["WALLET_PASSWORD"],
    ssl_server_dn_match=False,
    ssl_context=ssl_context,
)

profile = select_ai.Profile(profile_name=os.environ["SELECT_AI_PROFILE"])
print(profile.run_sql(prompt="show the current date"))
PY

python select_ai_profile_test.py

Useful URLs

After startup, these are handy for local demos:

  • APEX: https://localhost:8443/ords/apex
  • Database Actions: https://localhost:8443/ords/sql-developer

Stop and clean up

Stop the container:

podman stop adb-free

Start it again later:

podman start adb-free

Remove it entirely:

podman rm -f adb-free

Clone this wiki locally