Install AI Agent Skills  View Python SDK

Understanding Container Setup Configuration

Use Autonomous AI Database Free Container for the required setup order and commands. This page explains why the values are used, when optional changes are useful, and how the database, ORDS, and Python SDK fit together. It includes optional commands for checking and tuning ORDS; they are not required for a default setup.

The container is a local development database, not an Oracle Cloud database. Its image, database files, wallet, ORDS configuration, and test data are stored in the local container runtime. It is suitable for learning, SDK development, and repeatable local tests; it is not a production deployment or a substitute for backups and high availability.

When you finish

The parent page creates a local ADB-Free database, configures ORDS for the VecDB REST API, creates a vector schema, and loads an embedding model. The values you need for the SDK are:

Use the Python SDK connection guide for authentication and OAuth commands.

Find the information you need

If you need to understand… Go to
resource requirements and runtime sizing Prerequisites and resource sizing
database storage and session limits Persistent storage configuration
container run options and volume behavior Container parameters
password requirements for image variables and the vector schema Password values
startup readiness Startup and readiness
ORDS compatibility or upgrade conditions Check the ORDS version
ORDS connection pool settings Configure the ORDS connection pool
vector schema grants and database settings Vector user and database settings
outbound proxy Configure an outbound proxy
SDK endpoint and local TLS Local endpoints, TLS, and SDK connections
trust the local ORDS certificate Trust the local HTTPS certificate
errors or recovery steps Troubleshooting

Prerequisites and resource sizing

The documented Podman baseline is 4 CPUs, 8 GB of runtime memory, and a 100 GB virtual disk for basic single-user development. Increase runtime memory to 16 GB only if model loading, vector-index creation, larger batches, or concurrent SDK tests require it and the host has enough memory.

Container runtime configuration

Setting What it controls Start with Increase it when
Podman machine CPUs CPU available to the container runtime 4 Startup, model loading, or index creation is CPU-bound and the host has spare capacity
Podman machine memory Total memory available to the database, ORDS, and other containers 8 GB for basic setup Increase to 16 GB only if model loading, indexes, or concurrent tests require it and the host has enough memory
Podman machine disk Virtual disk for the guest, image layers, database files, wallet, logs, and other containers 100 GB for basic setup Increase it for persistent data, repeated model loads, indexes, or multiple images
--shm-size Container /dev/shm shared-memory ceiling 4 GB in the parent setup command Increase above 4 GB if larger batches, model loading, vector indexes, or concurrent requests exhaust shared memory

Persistent storage configuration

The ADB-Free database has fixed service limits, including 20 GB of database storage and a maximum of 30 simultaneous database sessions. More Podman memory, disk, or CPUs provide host-side headroom; they do not increase those database limits.

A 100 GB Podman disk is not equivalent to the database’s 20 GB storage limit. The Podman disk also contains the guest operating system, image layers, wallet, logs, and other containers. It can fill before the database reaches its own limit. Monitor free space before loading models or data.

The parent page sets --disk-size 100 when creating a Podman machine, so the initial setup does not depend on a changing Podman default. Monitor free space as images, models, and data accumulate. Omitting --disk-size for an existing machine does not resize it. Check podman machine init --help on the target system for that Podman’s supported options.

The Podman virtual machine must leave memory and CPU for the host operating system, browser, editor, terminal, and SDK process. An 8 GB laptop is not recommended for this setup. On a 16 GB laptop, use the 8 GB baseline for light work and close other applications before considering an increase. Increase runtime memory to 16 GB only when the workload requires it and the host has enough free capacity; a 32 GB or larger laptop can generally support this allocation along with 4 CPUs, a 100 GB virtual disk, and 4 GB of shared memory.

Container parameters

The parent page’s run command defines the local runtime contract:

Parameter Purpose If it is changed or omitted
-p host-port:container-port Publishes a container port on the host using Podman’s default host binding Change only the host-side number and update every URL that uses it. To restrict access to this computer, use the optional loopback address described in troubleshooting.
-v OracleDBData:/u01/data Persists database state across container restarts Removing the volume or using a different volume starts a different database.
--shm-size=4g Sets the /dev/shm ceiling The 4 GB ceiling provides headroom for vector and model work; memory is used as needed.
WORKLOAD_TYPE=ATP Selects the Transaction Processing workload Use ATP for the service and SDK workflow documented here. Changing it does not convert an existing database in a persistent volume.
WALLET_PASSWORD Protects the wallet generated by the image Store it securely; it is different from ADMIN_PASSWORD and application credentials.
ADMIN_PASSWORD Initial administrative database password Use it for Database Actions and administrative SQL, not for application requests.
--cap-add SYS_ADMIN and --device /dev/fuse Gives the image the filesystem capabilities it needs Omitting either option can prevent initialization.

The parent page uses a 4 GB shared-memory ceiling for vector and model work. If a workload still exhausts /dev/shm, recreate the container with a larger --shm-size while preserving OracleDBData. The size cannot be changed on an existing container by restarting it.

Password values

For the image’s ADMIN_PASSWORD, use 12–30 characters with at least one uppercase letter, one lowercase letter, and one digit. Do not include the username admin. WALLET_PASSWORD must be 8–30 characters and combine alphabetic characters with digits or special characters.

For values substituted into the setup commands, ASCII letters and digits are the simplest choices and avoid shell quoting surprises. Use the same pattern for <VECTOR_USER_PASSWORD>; the SQL example encloses it in double quotes, so do not include a double-quote character in that value.

Startup and readiness

On macOS or Windows, after podman machine start, confirm that the Podman API is reachable before creating the volume or container:

podman info

The command should return host and runtime information. A VM listed as running may still have failed during guest initialization. If podman info reports a connection error, use Podman machine troubleshooting before continuing.

The first startup initializes the image and database and can take several minutes. The log message Oracle REST Data Services initialized indicates that ORDS completed its startup sequence. Pressing Ctrl+C after following logs only stops log display; it does not stop the container.

Use these read-only checks to inspect startup:

podman ps -a --filter name=adb-free
podman logs -f --tail 200 adb-free

Use docker ps and docker logs for Docker. If the container is running but ORDS is not ready, inspect logs before changing memory or recreating the container. Repeated restarts during first initialization can leave a partially initialized environment; preserve the volume and use the troubleshooting guidance before creating a new one.

ORDS configuration

The parent setup uses the ORDS runtime bundled with the ADB-Free image and does not download or replace ords.war. ORDS starts with the database container. The setup enables a lowercase schema mapping for the vector user; that mapping is separate from the image-wide ORDS runtime.

Check the ORDS version and update only if needed

To inspect the bundled runtime without changing it:

podman exec adb-free ords --version

Use docker exec in place of podman exec for Docker. This is a read-only check. The Python SDK workflow requires ORDS 26.2.2 or later. If the bundled version meets that minimum, no ORDS upgrade is needed for this workflow. In particular, changing the JDBC pool’s MaxLimit is a configuration change and does not require upgrading ORDS.

Upgrade ORDS only if the bundled version is below the SDK minimum or an Oracle fix requires a newer release. The Free Container Image bundles ORDS and other database tools; to update built-in tools, move to a newer supported image and follow Oracle’s Free Container Image migration guidance. Preserve and migrate the database volume and any ORDS configuration according to that guidance. Do not replace ords.war as an isolated step in this setup.

The Console, DB API, and REST Enabled SQL use separate ORDS features. A successful container health check does not prove the vector user’s lowercase schema mapping exists; the parent setup creates that mapping in its SQL step.

Select the database service

The service passed to ORDS must exist in the current wallet and must match the selected workload. For an ATP-style database, common service suffixes are:

Service Typical use
<database>_tp General Transaction Processing work and a good default for SDK or REST traffic
<database>_tpurgent Urgent, latency-sensitive Transaction Processing work; use sparingly because it receives higher priority
<database>_high Higher-priority work that needs more resources per request
<database>_medium General work with balanced concurrency and resources
<database>_low Lower-priority background work and higher concurrency

Use the exact alias shown in the wallet’s tnsnames.ora; service availability can vary by image and workload. For an ATP-style database, _tp is appropriate for ordinary SDK or REST requests and _low can be used for lower-priority background work. Choose another service only when its resource priority or concurrency fits the workload. An ADW workload has different service availability, so do not copy ATP service names into an ADW configuration.

Configure the ORDS connection pool

The ORDS JDBC pool controls how many database sessions ORDS opens. jdbc.InitialLimit sets how many connections are created initially; a lower value reduces startup session and memory use but can add latency while more connections are created. jdbc.MaxLimit caps the pool and therefore limits concurrent REST work. Oracle recommends using the ORDS command-line interface to change these settings; see ORDS configuration settings.

ADB-Free has a ceiling of 30 simultaneous database sessions. Use an initial limit of 8 and a maximum of 20 as the documented local profile when REST work competes with direct SQL, SDK workers, or maintenance. The initial limit starts ORDS with eight connections; the pool can grow to 20, leaving up to 10 sessions for other clients. Reduce the values on a constrained host or when you see session pressure. Increase MaxLimit only when measured REST concurrency needs it and the other clients still have enough sessions. A lower maximum can reduce throughput when many REST requests arrive together.

Check the current values:

podman exec adb-free ords --config /u01/ords config get jdbc.InitialLimit
podman exec adb-free ords --config /u01/ords config get jdbc.MaxLimit

When the current values need tuning, set the local profile and restart the container so ORDS uses the new pool limits:

podman exec adb-free ords --config /u01/ords config set jdbc.InitialLimit 8
podman exec adb-free ords --config /u01/ords config set jdbc.MaxLimit 20
podman restart adb-free

Use docker exec and docker restart for Docker. Restarting briefly interrupts ORDS requests, but the database persists when the existing OracleDBData volume remains attached. These commands tune the pool; they do not upgrade the ORDS runtime.

Preserve ORDS configuration

Stopping and starting the same container preserves its ORDS runtime and configuration. Removing and recreating the container can discard files stored only in its writable layer. Keep the OracleDBData volume and follow the parent page’s storage guidance if the container itself must be recreated.

Vector user and database settings

The parent page’s SQL performs four related tasks:

The DATA_PUMP_DIR grant is an Oracle directory object privilege, not a host-file permission. DBMS_CLOUD-backed vector loads can be accepted as jobs and then fail asynchronously with ORA-06564 when the schema lacks READ and WRITE. Use the troubleshooting procedure to inspect and restore those grants.

The lowercase mapping is significant. A database user named VECTOR_USER is reached through an ORDS path such as /ords/vector_user/. The database username remains case-insensitive in normal SQL authentication, but the URL mapping must match the lowercase value used in the endpoint.

The bundled image configures its ORDS pool runtime account. The vector schema needs only the lowercase mapping created by the parent setup; configure a separate ORDS runtime user only when using a custom ORDS deployment. See Oracle’s ORDS runtime-user reference.

The concise parent example uses an unlimited DATA quota so the basic setup does not fail because of an arbitrary schema quota. If your local policy requires a bounded quota, set one after checking DATA tablespace usage and reserve headroom within the ADB-Free storage limit.

Configure an outbound proxy

Proxy configuration has four separate layers. Configure only the layers that need outbound access:

  1. image pulls by Podman or Docker
  2. environment variables for processes inside the running container
  3. the ADB-Free database APIs
  4. the Python SDK process

Configure image pulls and container processes

The proxy -e options in the parent page set environment variables inside the ADB-Free container after its image has been pulled. They do not configure the registry request used to download the image.

For Podman machine or ADB-Free image download failures, use the registry and proxy troubleshooting steps. For Docker, image downloads may require Docker Engine daemon proxy settings. When a process inside the ADB-Free container needs outbound proxy access, use the alternate proxy options in the parent setup command.

Podman passes proxy variables from the host Podman process into containers by default; explicit -e options in the parent command override those values. Docker CLI proxy settings can provide proxy variables to containers, while Docker Engine registry access may require daemon-level configuration. See the Podman run environment documentation, Docker CLI proxy configuration, and Docker daemon proxy configuration.

Configure the ADB-Free database APIs

Follow the executable Configure an outbound proxy when required step on the parent page. It sets the database-level HTTP_PROXY property through DBMS_CLOUD_CONTAINER_ADMIN. Run it from an administrator SQL Worksheet only when the database must reach Object Storage or another external service through a proxy, and run it before loading a model.

This setting is different from HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment settings supplied to processes inside the container. Container environment variables apply to processes running inside the container; the database-level property controls outbound calls made by the ADB-Free database APIs. Configure both only when both layers need proxy access. Do not replace the image-managed TLS wallet or add a CDB/PDB network ACL for this local workflow.

For the image-supported container options and networking behavior, see Use the Autonomous AI Database Free Container Image.

Configure the Python SDK process

If the Python process uses a proxy, set Configuration.proxy. See Configure TLS, a proxy, and retries for SDK setup examples. For exact settings, see Configuration custom CA, proxy, and timeout/retry.

Local endpoints, TLS, and SDK connections

The Console URL and SDK REST endpoint share the host, port, and lowercase ORDS mapping but use different paths:

Use the SDK endpoint, not the Console URL, in Configuration. For username/password or OAuth bearer-token commands, use the Python SDK connection guide, which covers credential creation, token retrieval, and secure secret handling.

Trust the local HTTPS certificate

The ADB-Free container creates a self-signed certificate for its local HTTPS service. Your browser can show a certificate warning when you first open the Console URL. For local development, copy the certificate used by ORDS from the running container and add it to your host trust store. The ORDS certificate is /u01/ords/self-signed.crt; do not copy adb_container.cert from the database wallet because it is not the certificate served on port 8443. If you recreate the container, repeat this procedure because the certificate is generated when the container starts.

Copy the certificate from the running container using your runtime:

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 the trust store for your operating system:

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

Alternatively, open Keychain Access, add self-signed.crt to the login keychain, and set the certificate trust policy to Always Trust. See Add certificates to a keychain using Keychain Access.

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

Firefox can use its own certificate store, so you might need to import the certificate in Firefox as well.

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 to the trust store, close all browser windows and restart your browser. Open the Console URL and confirm that it loads without a certificate warning.

This step removes the certificate warning in the browser. Before running the Python quickstart notebooks, set ssl_ca_cert in Configuration to the host path of the copied self-signed.crt file. This lets the SDK verify the local ORDS certificate. See the quickstart client example. If a notebook reports Connection refused, confirm that the container is running, ORDS is ready, and port 8443 is published; a refused connection means the endpoint is not accepting requests. See Database Actions access troubleshooting and ORDS startup troubleshooting.

Do not use -k as the normal solution. It disables certificate verification and should be limited to temporary local diagnostics.

Container lifecycle

Stopping and starting adb-free preserves the database volume. Recreating the container is safe only when the OracleDBData volume is retained and any ORDS runtime or configuration that was stored only in the container filesystem is restored according to the parent page. Removing the volume intentionally resets the local database, users, wallet, ORDS state, and application data.

Troubleshooting

For diagnosis and recovery, see Troubleshoot Autonomous AI Database Free Container Setup.