Autonomous AI Database Free Container

Use the Autonomous AI Database Free container image to run a local Oracle AI Database 26ai environment for development and testing. This guide supports Docker and Podman and configures ORDS so the Oracle VecDB Python SDK can connect over HTTPS.

When you finish

You will have a running local Oracle AI Database 26ai environment with ORDS configured for the VecDB REST API, a <VECTOR_USER> database user, and an embedding model such as all_MiniLM_L12_v2 loaded in the database. Save these credentials and URLs for the quickstart:

the <VECTOR_USER> name and password
the Console URL for the browser-based Vector Database Console
the SDK REST endpoint for Python requests

The Console URL and SDK REST endpoint use the same host and REST URL mapping but different paths. The quickstart uses the SDK REST endpoint.

Choose this setup when you want a local database for development and testing.

Prerequisites

Install Docker or Podman on your development computer. For basic development, allocate 4 CPUs and 8 GB of memory to Docker. The Podman example assigns the same CPU and memory resources to its VM, with a 100 GB virtual disk. Increase runtime memory to 16 GB only if your workload requires it and your computer has enough memory to leave capacity for the host operating system and other applications.

Tip: Check your computer’s capacity before changing the Podman VM’s CPU and memory. Leave resources for the host operating system and other applications. See resource sizing.

The Step 3 --shm-size=4g option sets the container’s /dev/shm limit, separate from the Podman VM’s --memory allocation. See container parameter details if you need to adjust it.

Make sure these host ports are available:

1521 and 1522 for database connections
8443 for HTTPS and ORDS
27017 for the document database interface

If a host port is already in use, change only the host-side port in the corresponding -p option. Keep the container-side port unchanged. For example, change -p 8443:8443 to -p 9443:8443, then use port 9443 in the Console URL and SDK REST endpoint. See host-port troubleshooting if the port conflict persists.

The container image can take several minutes to download and start.

1. Start the container runtime

Start your container runtime:

Docker
Podman

Start Docker Desktop or Docker Engine. On Windows, use Linux containers. In Docker Desktop, open Settings > Resources and allocate at least 4 CPUs and 8 GB of memory. Verify the runtime:

docker info

For a first setup, create and start the Podman machine. On later runs, skip podman machine init and start the existing machine.

podman machine init --cpus 4 --memory 8192 --disk-size 100
podman machine start
podman machine list

If your network requires an HTTP proxy to download the machine image or the ADB-Free image, use these alternate commands and replace the proxy placeholders:

HTTP_PROXY="<HTTP_PROXY>" HTTPS_PROXY="<HTTPS_PROXY>" podman machine init --cpus 4 --memory 8192 --disk-size 100
HTTP_PROXY="<HTTP_PROXY>" HTTPS_PROXY="<HTTPS_PROXY>" podman machine start
podman machine list

For an existing machine, run only podman machine start and podman machine list; include proxy assignments on the start command if your network requires them. Continue when podman machine list returns host and runtime information. If it fails, use the relevant guide:

Podman machine startup troubleshooting
Registry and proxy troubleshooting for machine image download failures
Setup diagnostics for Docker runtime errors

2. Create persistent database storage

On first setup, create a named volume to preserve database files across container restarts. Reuse the volume if it already exists. Deleting it removes the database and users.

Docker
Podman

docker volume create OracleDBData
docker volume inspect OracleDBData

podman volume create OracleDBData
podman volume inspect OracleDBData

The final command should identify OracleDBData. If creation or inspection fails, use setup diagnostics. If the container later reports no space, see container storage troubleshooting.

For volume persistence and the storage used by the database, image layers, wallet, and logs, see persistent storage configuration.

3. Start the ADB-Free container

Start the Oracle ADB-Free container. Replace the password placeholders with strong values, and do not commit them to source control. If Podman needs a proxy, add the options shown after the runtime command before --name adb-free.

Tip: Use ASCII letters and digits in these placeholders to avoid shell and SQL quoting surprises. For the exact length and composition rules, see password values.

Note: If docker run or podman run reports that the container name adb-free is already in use, see The container name is already in use to check the image and replace an outdated container while retaining the database volume. For a complete reset that removes the old container and its database volume, see Reset and recovery. This reset permanently deletes the local database and its stored state.

On the first run, Docker or Podman downloads the image before creating the container. Watch the layer-download progress in the same terminal and wait for the command to return a container ID. The final status check below confirms that the container started; Step 4 confirms that database and ORDS startup finished.

Docker
Podman

Docker on macOS, Linux, or WSL:

docker run -d \
  -p 1521:1522 \
  -p 1522:1522 \
  -p 8443:8443 \
  -p 27017:27017 \
  -v OracleDBData:/u01/data \
  --shm-size=4g \
  -e WORKLOAD_TYPE=ATP \
  -e WALLET_PASSWORD="<WALLET_PASSWORD>" \
  -e ADMIN_PASSWORD="<ADMIN_PASSWORD>" \
  --cap-add SYS_ADMIN \
  --device /dev/fuse \
  --name adb-free \
  ghcr.io/oracle/adb-free:latest-26ai
docker ps -a --filter name=adb-free

Windows PowerShell:

docker run -d `
  -p 1521:1522 `
  -p 1522:1522 `
  -p 8443:8443 `
  -p 27017:27017 `
  -v OracleDBData:/u01/data `
  --shm-size=4g `
  -e WORKLOAD_TYPE=ATP `
  -e WALLET_PASSWORD="<WALLET_PASSWORD>" `
  -e ADMIN_PASSWORD="<ADMIN_PASSWORD>" `
  --cap-add SYS_ADMIN `
  --device /dev/fuse `
  --name adb-free `
  ghcr.io/oracle/adb-free:latest-26ai
docker ps -a --filter name=adb-free

Podman on macOS, Linux, or WSL:

podman run -d \
  -p 1521:1522 \
  -p 1522:1522 \
  -p 8443:8443 \
  -p 27017:27017 \
  -v OracleDBData:/u01/data \
  --shm-size=4g \
  -e WORKLOAD_TYPE=ATP \
  -e WALLET_PASSWORD="<WALLET_PASSWORD>" \
  -e ADMIN_PASSWORD="<ADMIN_PASSWORD>" \
  --cap-add SYS_ADMIN \
  --device /dev/fuse \
  --name adb-free \
  ghcr.io/oracle/adb-free:latest-26ai
podman ps -a --filter name=adb-free

Windows PowerShell:

podman run -d `
  -p 1521:1522 `
  -p 1522:1522 `
  -p 8443:8443 `
  -p 27017:27017 `
  -v OracleDBData:/u01/data `
  --shm-size=4g `
  -e WORKLOAD_TYPE=ATP `
  -e WALLET_PASSWORD="<WALLET_PASSWORD>" `
  -e ADMIN_PASSWORD="<ADMIN_PASSWORD>" `
  --cap-add SYS_ADMIN `
  --device /dev/fuse `
  --name adb-free `
  ghcr.io/oracle/adb-free:latest-26ai
podman ps -a --filter name=adb-free

When the container needs outbound proxy access, add these alternate options to the Podman run command before --name adb-free and replace the placeholders:

-e HTTP_PROXY="<HTTP_PROXY>" \
-e HTTPS_PROXY="<HTTPS_PROXY>" \
-e NO_PROXY="localhost,127.0.0.1,::1" \

For Windows PowerShell, use this equivalent block with backticks:

-e HTTP_PROXY="<HTTP_PROXY>" `
-e HTTPS_PROXY="<HTTPS_PROXY>" `
-e NO_PROXY="localhost,127.0.0.1,::1" `

These -e options set proxy values inside the running ADB-Free container. To allow Podman to pull the image from GHCR, use the proxy-enabled machine command in step 1. See registry and proxy troubleshooting if the image pull fails. For database model downloads through DBMS_CLOUD, also configure the database proxy in step 5.

For an explanation of the container options, shared-memory sizing, workload, and port mapping, see container parameter details.

The final command should list adb-free as Up; it can still be initializing. If the command fails or the container is not listed, use the relevant guide:

4. Wait for ADB-Free and bundled ORDS

The first startup initializes the database and ORDS and can take ten minutes or more. Wait for startup to finish before continuing. This setup uses the ORDS runtime bundled with the ADB-Free image; it does not download or replace the ORDS runtime. Check the container health and follow the logs for your runtime:

Docker
Podman

docker inspect adb-free --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}no healthcheck{{end}}'
docker logs -f --tail 100 adb-free

podman inspect adb-free --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}no healthcheck{{end}}'
podman logs -f --tail 100 adb-free

The health command can initially report starting. Follow the logs until they include Oracle REST Data Services initialized, then press Ctrl+C to stop log display; the container keeps running. Rerun the health command. Continue to Step 5 when it reports healthy and the log includes the ORDS initialization message. If the image reports no healthcheck, use the ORDS log message as the readiness check.

Optionally, confirm that the host can reach the ORDS endpoint:

curl --noproxy '*' -k -sS -o /dev/null -w 'HTTP %{http_code}\n' 'https://127.0.0.1:8443/ords/'

In Windows PowerShell, use curl.exe instead of curl. An HTTP status confirms that the host received a response from ORDS; a connection error means it is not reachable yet. If you changed the published host port, replace 8443 with that port. This temporary probe uses -k because the local certificate has not yet been trusted. Do not disable certificate verification in application code; see the certificate instructions in Step 5.

If startup does not finish, see ORDS startup troubleshooting. For more about readiness checks, see startup and readiness.

Note: ORDS is bundled with the image. Changing its pool limit does not require a software upgrade. See ORDS version and update guidance to check compatibility, ORDS pool configuration to tune jdbc.MaxLimit, or ORDS startup troubleshooting if ORDS does not initialize or requests fail.

5. Prepare a vector user

Use Database Actions inside the container to create the user that your Python application will use:

Prerequisite: Add and trust the local HTTPS certificate

Before opening Database Actions or running the Python quickstart notebooks, copy the ORDS certificate from the container and trust it on your development computer. The local ORDS endpoint uses a self-signed certificate. Without this prerequisite, quickstart notebooks may fail to connect to local ORDS. If a notebook reports Connection refused, also confirm that the container is running, ORDS is ready, and port 8443 is published. Certificate trust errors usually report a TLS verification failure; trusting a certificate does not start an unavailable service. See ORDS startup troubleshooting and Database Actions access troubleshooting for readiness and port checks.

Copy the certificate from the running container:

Docker
Podman

docker cp adb-free:/u01/ords/self-signed.crt ./self-signed.crt

podman cp adb-free:/u01/ords/self-signed.crt ./self-signed.crt

Add the certificate to your operating-system trust store:

security add-trusted-cert -r trustRoot -p ssl -k "$HOME/Library/Keychains/login.keychain-db" ./self-signed.crt

Alternatively, use Keychain Access to add the certificate to the login keychain and set its trust policy to Always Trust.

Import-Certificate -FilePath .\self-signed.crt -CertStoreLocation Cert:\CurrentUser\Root

Firefox may require importing the certificate into its own certificate store.

On Debian or Ubuntu:

sudo cp ./self-signed.crt /usr/local/share/ca-certificates/self-signed.crt
sudo update-ca-certificates

On RHEL, Fedora, or Oracle Linux:

sudo cp ./self-signed.crt /etc/pki/ca-trust/source/anchors/self-signed.crt
sudo update-ca-trust

After adding the certificate, close all browser windows and restart the browser so it reloads the trust store. Firefox may require importing the certificate into its own store before you restart it. In step 1 below, open Database Actions and confirm that the browser shows no certificate warning.

Note: Trusting this certificate in the operating-system or browser trust store applies to browser access. The Python SDK may use a separate CA bundle. For local ADB-Free connections, set ssl_ca_cert in Configuration to the copied self-signed.crt file. The quickstart client example shows the code.

If you recreate the container, copy and trust its newly generated certificate again. For more background and future reference, see the certificate procedure on the details page.

Tip: If Database Actions times out at localhost, try another browser or the IPv4 loopback address. Do not use the IPv6 literal [::1] to sign in: although it may display the sign-in page, authentication fails. See Database Actions access troubleshooting for an IPv6 connectivity check that keeps the localhost hostname.

Open Database Actions and confirm that no certificate warning appears.
Sign in as admin with the value of ADMIN_PASSWORD.
Open a SQL Worksheet and run the following statements. Replace <VECTOR_USER> and <VECTOR_USER_PASSWORD> with the username and password you want to use for your Python application. For a password that fits the SQL example, see password values.

CREATE USER <VECTOR_USER> IDENTIFIED BY "<VECTOR_USER_PASSWORD>";

GRANT DB_DEVELOPER_ROLE, CREATE MINING MODEL TO <VECTOR_USER>;
GRANT EXECUTE ON DBMS_CLOUD TO <VECTOR_USER>;
GRANT READ, WRITE ON DIRECTORY DATA_PUMP_DIR TO <VECTOR_USER>;

BEGIN
  ORDS_ADMIN.ENABLE_SCHEMA(
    p_schema              => UPPER('<VECTOR_USER>'),
    p_enabled             => TRUE,
    p_url_mapping_type    => 'BASE_PATH',
    p_url_mapping_pattern => LOWER('<VECTOR_USER>'),
    p_auto_rest_auth      => FALSE
  );
END;
/

ALTER USER <VECTOR_USER> QUOTA UNLIMITED ON DATA;

Run these statements as ADMIN. The directory grant is required for DBMS_CLOUD-backed vector loads; see troubleshooting missing DATA_PUMP_DIR permissions. ORDS_ADMIN.ENABLE_SCHEMA enables the schema and creates the lowercase URL mapping used by the SDK endpoint.

This step succeeds when every statement completes without an error. If the schema is locked, lacks quota, or cannot call the API, see vector-user troubleshooting. If the schema URL later returns 404, check the ORDS mapping in ORDS startup troubleshooting.

Configure an outbound proxy when required

If your network requires an HTTP(S) proxy to download models or access Object Storage, run the following from the administrator SQL Worksheet before loading a model. Replace the placeholder directly with your proxy URL:

BEGIN
  DBMS_CLOUD_CONTAINER_ADMIN.SET_DATABASE_PROPERTY(
    'HTTP_PROXY', 'http://<proxy-host>:<proxy-port>');
END;
/

Do not run this step when your environment has direct outbound access. This database-level setting is separate from HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment settings passed to the container; see proxy configuration details. If a model download cannot reach Object Storage, see registry and Object Storage troubleshooting.

For the privilege rationale, ORDS URL mapping, quota guidance, and session or tablespace checks, see vector user configuration details.

6. Load an embedding model and get the local REST URL

After creating the vector user, sign out of the administrator session and update the following URL before opening Database Actions. Replace <vector_user> with the REST URL mapping for <VECTOR_USER>. This is the vector_user part of the URL; it is not necessarily the same as the user name.

Warning: Use the lowercase REST URL mapping in the /ords/<vector_user>/ segment. Do not use the uppercase <VECTOR_USER> database user placeholder in this part of the URL. For example, a database user named VECTOR_USER uses /ords/vector_user/.

Console URL — open in a browser

https://localhost:8443/ords/<vector_user>/_sdw/?nav=vector-db

The quickstart uses integrated embeddings. Load the all_MiniLM_L12_v2 model for the quickstart. If you load a different model, use its name in the model value in the quickstart.

In the Vector Database Console, select the Models tab.
Select the context menu for the model you want to use, and then select Load.
Confirm the operation and wait for the model status to change to Available.

The model is ready when its status is Available. If loading fails while fetching the model, see Object Storage and proxy troubleshooting.

For more information, see Load a Model Using the Vector Database Console.

SDK REST endpoint — use in `Configuration`

https://localhost:8443/ords/<vector_user>/_/db-api/stable/vecdb/

When you configure the Python client, use the endpoint shown with either username="<VECTOR_USER>" and its password or a bearer access token. If the SDK does not trust the local self-signed certificate through your operating system, provide the copied certificate through the SDK’s ssl_ca_cert configuration option.

For authentication and client setup examples, see Connect to Oracle AI Database with Python.

For the host certificate trust procedure, see local TLS trust details. If the SDK rejects the certificate, returns 401 Unauthorized, or OAuth token retrieval fails, see TLS troubleshooting, REST authentication troubleshooting, or OAuth troubleshooting.

Troubleshoot setup issues

If you need a starting point for another setup problem, use troubleshooting diagnostics. The full troubleshooting guide has recovery steps for the container, database, ORDS, TLS, authentication, and proxy.

Next steps

Continue with Install the SDK in the quickstart. Use the SDK REST endpoint shown in the previous section, <VECTOR_USER>, and the password you created when you configure the client.