Deploy and Host Floci OCI Emulator on Railway

Floci OCI is a fast, free, and open-source Oracle Cloud Infrastructure emulator for development, testing, automation, and CI/CD workflows.

It provides OCI-compatible APIs for services such as Identity and IAM, Object Storage, Queue, Streaming, Vault, KMS, Secrets, and Functions without requiring a real Oracle Cloud account or production OCI infrastructure.

About Hosting Floci OCI

This template deploys Floci OCI on Railway using the official floci/floci-oci:latest Docker image.

Floci OCI exposes its supported Oracle Cloud Infrastructure APIs through a unified HTTP endpoint on port 4599. Applications, OCI SDKs, OCI CLI, Terraform, OpenTofu, and automated test suites can connect to the Railway public domain instead of real OCI endpoints.

Persistent emulator state is stored in a Railway volume mounted at /app/data, allowing supported resources to survive container restarts and redeployments.

OCI Functions can normally execute through a Docker-backed fnproject/fnserver sidecar. Railway does not expose the host Docker socket, so this template enables Functions mock mode instead.

Common Use Cases

Develop applications against OCI-compatible APIs without using production Oracle Cloud resources
Test Object Storage, Queue, Streaming, Vault, KMS, Secrets, and IAM integrations
Run integration and end-to-end tests against isolated OCI-like infrastructure
Test OCI SDK and OCI CLI integrations
Use Terraform or OpenTofu against emulated OCI APIs
Build CI/CD workflows without requiring real OCI environments
Test API and middleware integrations that depend on Oracle Cloud services
Provide a shared remote OCI emulator for development teams

Dependencies for Floci OCI Hosting

Official floci/floci-oci:latest Docker image
Railway public networking on port 4599
Railway persistent volume mounted at /app/data

How to Use Floci OCI

After deployment, Railway provides a public domain similar to:

https://your-floci-oci.up.railway.app

Use this Railway domain as the OCI emulator endpoint.

For the examples below:

export FLOCI_OCI_ENDPOINT="https://your-floci-oci.up.railway.app"

Replace the example URL with your actual Railway public domain.

1. Check Floci OCI Health

Verify that the emulator is running:

curl "$FLOCI_OCI_ENDPOINT/_floci-oci/health"

A successful response confirms that Floci OCI is available.

2. Configure OCI CLI

Floci OCI can work with locally generated OCI credentials.

Create a throwaway private key:

mkdir -p ~/.oci
openssl genrsa -out ~/.oci/floci_key.pem 2048

Create an OCI CLI profile:

[FLOCI]
user=ocid1.user.oc1..flocilocaluser0000000000000000000000000000000000000000000000
fingerprint=aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99
tenancy=ocid1.tenancy.oc1..flocilocaltenancy0000000000000000000000000000000000000000
region=us-ashburn-1
key_file=~/.oci/floci_key.pem

Do not use this profile against real OCI infrastructure.

3. Test Object Storage

Get the configured Object Storage namespace:

oci --profile FLOCI os ns get \
  --endpoint "$FLOCI_OCI_ENDPOINT"

The default namespace is:

floci-local

Create a bucket:

oci --profile FLOCI os bucket create \
  --endpoint "$FLOCI_OCI_ENDPOINT" \
  --compartment-id ocid1.tenancy.oc1..flocilocaltenancy0000000000000000000000000000000000000000 \
  --namespace floci-local \
  --name my-bucket

Upload an object:

echo "Hello from Floci OCI on Railway" > hello.txt

oci --profile FLOCI os object put \
  --endpoint "$FLOCI_OCI_ENDPOINT" \
  --namespace floci-local \
  --bucket-name my-bucket \
  --name hello.txt \
  --file hello.txt

List objects:

oci --profile FLOCI os object list \
  --endpoint "$FLOCI_OCI_ENDPOINT" \
  --namespace floci-local \
  --bucket-name my-bucket

4. Test IAM

List compartments:

oci --profile FLOCI iam compartment list \
  --endpoint "$FLOCI_OCI_ENDPOINT" \
  --compartment-id ocid1.tenancy.oc1..flocilocaltenancy0000000000000000000000000000000000000000

This request is handled by the Floci OCI Identity service instead of real Oracle Cloud.

5. Using the OCI SDK

Python

import oci

config = {
    "user": "ocid1.user.oc1..flocilocaluser0000000000000000000000000000000000000000000000",
    "fingerprint": "aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99",
    "tenancy": "ocid1.tenancy.oc1..flocilocaltenancy0000000000000000000000000000000000000000",
    "region": "us-ashburn-1",
    "key_file": "~/.oci/floci_key.pem",
}

client = oci.object_storage.ObjectStorageClient(
    config,
    service_endpoint="https://your-floci-oci.up.railway.app"
)

namespace = client.get_namespace().data

print(namespace)

OCI SDK clients should use the Railway public domain as their service_endpoint.

Supported OCI Services

Floci OCI provides emulation for Oracle Cloud Infrastructure APIs including:

Identity and IAM
Compartments
Users and groups
Object Storage
Queue
Streaming
Vault
Key Management Service
Secrets
Functions
Work Requests

Service coverage and implementation completeness may vary between releases.

OCI Functions on Railway

Floci OCI can normally execute OCI Functions using a real fnproject/fnserver container.

The standard architecture requires access to:

/var/run/docker.sock

Railway does not expose the host Docker socket to deployed services.

Therefore this template uses:

FLOCI_OCI_SERVICES_FUNCTIONS_MOCK="true"

With mock mode enabled:

Capability	Railway Template
Create Functions applications	✅
Create Functions	✅
List and manage Functions resources	✅
Functions management-plane APIs	✅
Real container execution	❌
Synthetic function invocation	✅
Docker socket required	❌

The Functions management plane remains available, while invocation returns a synthetic response rather than executing the configured function image.

Persistent Storage

This template uses:

FLOCI_OCI_STORAGE_MODE="persistent"
FLOCI_OCI_STORAGE_PERSISTENT_PATH="/app/data"

with a Railway volume mounted at:

/app/data

Floci OCI supports multiple storage modes:

Mode	Behavior
`memory`	Entire state is kept in memory and lost when the container stops
`persistent`	State is written to disk immediately after mutations
`hybrid`	In-memory operation with periodic asynchronous disk flushing
`wal`	Write-ahead logging for maximum durability

This Railway template uses persistent mode for predictable state retention across restarts.

Deleting the Railway volume will delete the persisted emulator state stored inside it.

Multi-Tenancy

Floci OCI supports tenancy-based isolation.

The tenancy OCID contained in the OCI request signing context is used as the resource isolation boundary.

Requests using different tenancy OCIDs therefore operate against isolated sets of resources.

Unsigned requests fall back to Floci OCI's configured default tenancy.

This makes it possible to test multi-tenant OCI workflows without provisioning multiple real Oracle Cloud tenancies.

Floci OCI vs Oracle Cloud Infrastructure

Feature	Floci OCI on Railway	Oracle Cloud Infrastructure
OCI-compatible APIs	✅	✅
Requires Oracle Cloud account	❌	✅
Requires production OCI credentials	❌	✅
Object Storage	✅	✅
IAM APIs	✅	✅
Queue & Streaming APIs	✅	✅
Vault / KMS / Secrets	✅	✅
Functions management plane	✅	✅
Real serverless execution	❌	✅
Persistent emulator state	✅	N/A
Development and CI	✅	✅
Production infrastructure	❌	✅

Why Deploy Floci OCI on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

Deploying Floci OCI on Railway provides a remotely accessible Oracle Cloud-compatible development environment with automatic HTTPS, persistent storage, OCI SDK and CLI compatibility, and simple infrastructure management without maintaining your own virtual machine.