DEV Community: sys-ronin

AdventureWorks SQL Server with Docker and DBeaver Keystore Helper

sys-ronin — Wed, 12 Aug 2026 20:36:41 +0000

I needed a local SQL Server with the AdventureWorks2022 sample database. Sounds like a 10-minute job, right? Run a container, restore a .bak, connect with DBeaver. Done.

It took two hours. Here's what actually happened, what broke, and the setup that finally worked.

The Goal

SQL Server 2022 running in Docker on Debian
Auto-restore AdventureWorks2022.bak on first boot
Connect from DBeaver without certificate errors
Survive restarts without re-restoring the database

What I Built

A Docker Compose setup with a custom entrypoint.sh that:

Starts SQL Server in the background
Polls sqlcmd every 2 seconds until the engine is ready
Checks if AdventureWorks2022 already exists (idempotent)
If not, runs RESTORE DATABASE ... WITH MOVE
Keeps the container alive

The database files live in a named Docker volume, so stopping and restarting the container doesn't wipe your data.

The Bugs That Weren't in the Tutorial

1. Permission denied on entrypoint.sh

I store my projects on Koofr (cloud-synced). chmod +x works on the host, but Docker bind-mounts the file without the execute bit. The container kept restarting with Permission denied.

Fix: Run the script through /bin/bash instead of relying on the shebang:

entrypoint: ["/bin/bash", "/usr/config/entrypoint.sh"]

2. "Access is denied" on master.mdf

SQL Server's default mssql user couldn't write to the Docker volume.

Fix: Added user: root to the compose service. Fine for local dev. Don't do this in production.

3. sqlcmd v18 won't connect without -C

SQL Server 2022 bundles sqlcmd in /opt/mssql-tools18/bin/. This version refuses to connect to localhost without explicitly trusting the self-signed certificate, even though it's the same machine.

Fix: Every sqlcmd call gets the -C flag. The healthcheck too.

4. DBeaver's JDBC driver demanded a keystore

I kept getting:

"keyStoreAuthentication" connection string keyword must be specified, if "keyStoreSecret" is specified

Clearing the properties in one connection didn't help — the driver had cached defaults somewhere. I spent 20 minutes in DBeaver preferences before giving up and creating a dummy Java keystore.

Fix: One keytool command to generate a fake .jks file, then four driver properties in DBeaver:

Property	Value
`keyStoreAuthentication`	`JavaKeyStorePassword`
`keyStoreLocation`	`/absolute/path/to/dummy.jks`
`keyStoreSecret`	`dummy123`
`trustServerCertificate`	`true`

It shouldn't be this hard to connect to a local database. But here we are.

DBeaver Connection — The Exact Settings

After the container is running, here's how to connect DBeaver without any certificate drama.

Main Tab

Setting	Value
Host	`localhost`
Port	`1433` (or whatever you set in `.env`)
Database	`AdventureWorks2022`
Authentication	SQL Server Authentication
User	`sa`
Password	your `.env` password

Driver Properties Tab

These are the properties that actually matter. Add or edit them here:

Property	Value	Why
`trustServerCertificate`	`true`	Tells the JDBC driver to accept the self-signed cert SQL Server generates on first boot. Without this, you get SSL handshake failures even on localhost.
`keyStoreAuthentication`	`JavaKeyStorePassword`	Tells the driver you're using a local JKS file, not Azure Key Vault.
`keyStoreLocation`	`/absolute/path/to/dummy.jks`	Points to the dummy keystore file. Use the absolute path — DBeaver doesn't resolve `~` here.
`keyStoreSecret`	`dummy123`	The password for the dummy keystore.

How to get there: Edit Connection → Driver Properties → scroll down or use the search box. If a property doesn't exist, right-click in the list and choose Add New Property.

Click Test Connection. It should say "Connected".

If You Don't Want the Keystore Hack

You can try resetting the driver completely:

Window → Preferences → Connections → Drivers → Microsoft JDBC Driver for SQL Server
Click Reset to Defaults (or delete and re-download)
In your connection: Driver Properties → gear icon → Reset to Defaults
Add back only: trustServerCertificate = true

Sometimes this works. Sometimes the keystore properties come back anyway. The dummy keystore is faster and more reliable.

The Repo

Everything is here: docker-compose.yml, entrypoint.sh, the keystore generator, and a full setup guide.

github.com/sjyotis/adventureworks2022-docker

Quick Start

git clone https://github.com/sjyotis/adventureworks2022-docker.git
cd adventureworks2022-docker
mv /path/to/AdventureWorks2022.bak backups/
docker compose up -d

Wait for the logs to show Restore completed successfully!, then connect DBeaver using the settings above.

Repo Structure

adventureworks2022-docker/
├── docker-compose.yml              # Main SQL Server container
├── .env                            # Password and port config
├── init/
│   └── entrypoint.sh              # Auto-restore on first boot
├── backups/
│   └── AdventureWorks2022.bak    # Drop your .bak here
├── dbeaver-keystore-fix.md        # Full keystore workaround guide
├── adventureworks-docker-setup.md # Complete implementation docs
└── keystore-generator/
    ├── docker-compose.yml         # One-shot keystore generator
    └── generate_keystore.py       # Python wrapper if you prefer

What This Actually Demonstrates

Docker Compose orchestration with health checks and named volumes
Bash scripting for service initialization and idempotency
SQL Server administration (RESTORE FILELISTONLY, WITH MOVE)
SSL/TLS debugging in client drivers
Cross-platform filesystem edge cases (cloud-synced storage stripping permissions)

It's not just "I ran a database in Docker." It's a complete local dev infrastructure setup that handles provisioning, initialization, persistence, and client connectivity across the full stack.

The Files

docker-compose.yml — SQL Server 2022 container with volume mounts and healthcheck
init/entrypoint.sh — Auto-restore script with startup polling
.env — Configurable SA password and port
backups/ — Drop your .bak here
dbeaver-keystore-fix.md — Standalone guide for the DBeaver certificate workaround

If you've ever fought with DBeaver certificates, SQL Server Docker permissions, or restore scripts that assume the database is already running, this repo is for you.

Pull requests welcome. Issues too — especially if you hit a new edge case I haven't seen yet.

[How to] Terraform Offline Provider Setup: Zero Downloads & Clean Repos with Local Mirrors (with script)

sys-ronin — Fri, 07 Aug 2026 19:47:04 +0000

Terraform Offline Provider Setup Guide

Using `.terraformrc` + `.terraform.d` for Zero-Download, Repo-Clean Infrastructure

1. The Problem

By default, Terraform:

Downloads providers from the internet on every terraform init
Creates a .terraform/ directory inside every project folder
Bloats repositories with cached plugins and lock files
Breaks in air-gapped or CI/CD environments without internet access

Result: Your repo is dirty, initialization is slow, and builds are non-deterministic.

2. The Solution

Use Terraform's CLI Configuration File (.terraformrc) to define a filesystem mirror. This tells Terraform to resolve providers from a local directory instead of the public registry.

Benefits:

Zero internet calls for known providers after initial setup
No .terraform/ directories inside project folders (only a tiny lock file)
Instant terraform init across all projects using the same provider version
Deterministic builds — every teammate uses the exact same binary
Air-gapped / CI-ready — works without internet once configured

3. Directory Structure

~/.terraform.d/
├── checkpoint_cache              # Terraform version check cache
├── checkpoint_signature
└── plugins-local/                # <-- Your local provider mirror
    └── registry.terraform.io/
        └── oracle/
            └── oci/
                ├── index.json
                ├── 6.20.0/
                │   └── linux_amd64/
                │       └── terraform-provider-oci_v6.20.0_x5   <-- extracted binary
                └── 5.47.0/
                    └── linux_amd64/
                        └── terraform-provider-oci_v5.47.0_x5

Important Naming Rules

Element	Rule
Directory path	Must follow `registry.terraform.io/<namespace>/<name>/<version>/<arch>/`
Binary name	Must be `terraform-provider-<name>_v<version>_x5`
No `.zip` files	Extract the binary; `.zip` files are ignored by `filesystem_mirror`
`index.json`	Optional — Terraform can work without it for simple mirrors

4. Step-by-Step Setup

Step 1: Create `~/.terraformrc`

This is the Terraform CLI configuration file. It lives in your home directory.

provider_installation {
  # Use local filesystem for oracle/oci provider
  filesystem_mirror {
    path    = "/home/unknown/.terraform.d/plugins-local"
    include = ["oracle/oci"]
  }

  # Everything else falls back to internet
  direct {
    exclude = ["oracle/oci"]
  }
}

Critical details:

File must be named exactly .terraformrc (not terraform.rc, not .terraformrc.txt)
Must reside in $HOME/.terraformrc (Linux/macOS) or %USERPROFILE%\terraform.rc (Windows)
The include pattern uses the full source address: registry.terraform.io/oracle/oci
Do not add /* at the end — oracle/oci is the correct pattern

Step 2: Prepare the Mirror Directory

mkdir -p ~/.terraform.d/plugins-local/registry.terraform.io/oracle/oci/6.20.0/linux_amd64

Step 3: Extract the Provider Binary

If you downloaded the provider as a .zip:

cd ~/.terraform.d/plugins-local/registry.terraform.io/oracle/oci/6.20.0/linux_amd64
unzip terraform-provider-oci_6.20.0_linux_amd64.zip
mv terraform-provider-oci_v6.20.0 terraform-provider-oci_v6.20.0_x5

Verify:

ls -la ~/.terraform.d/plugins-local/registry.terraform.io/oracle/oci/6.20.0/linux_amd64/
# Should show: terraform-provider-oci_v6.20.0_x5

Step 4: Configure `provider.tf` in Your Project

In every Terraform stack that uses this provider:

terraform {
  required_version = ">= 1.5.0"
  required_providers {
    oci = {
      source  = "oracle/oci"
      version = "6.20.0"
    }
  }
}

provider "oci" {
  tenancy_ocid     = var.tenancy_ocid
  user_ocid        = var.user_ocid
  fingerprint      = var.fingerprint
  private_key_path = var.private_key_path
  region           = var.region
}

What happens:

Terraform reads source = "oracle/oci" and version = "6.20.0"
It checks .terraformrc and finds a filesystem_mirror matching that address
It copies the binary from ~/.terraform.d/plugins-local/... into memory
No .terraform/providers/ directory is created in your project folder
State backends still work normally (S3, HTTP, local, etc.)

Step 5: Initialize and Verify

cd ~/oci-infra/shared
rm -rf .terraform/ .terraform.lock.hcl   # clean slate
terraform init

Expected output:

Initializing provider plugins...
- Finding oracle/oci versions matching "6.20.0"...
- Installing oracle/oci v6.20.0...
- Installed oracle/oci v6.20.0 (unauthenticated)

The key phrase is (unauthenticated). If you see (signed by a HashiCorp partner...), Terraform downloaded from the internet instead of your mirror.

5. Space Savings Breakdown

Before (Default Behavior)

oci-infra/
├── shared/
│   ├── .terraform/                 # ~180 MB
│   │   └── providers/
│   │       └── registry.terraform.io/
│   │           └── oracle/oci/6.20.0/...
│   └── .terraform.lock.hcl
├── vm-amd/
│   ├── .terraform/                 # ~180 MB (duplicate!)
│   └── .terraform.lock.hcl
└── vm-arm/
    ├── .terraform/                 # ~180 MB (duplicate!)
    └── .terraform.lock.hcl

Total: ~540 MB in project folders

After (Local Mirror)

~/.terraform.d/
└── plugins-local/
    └── oracle/oci/6.20.0/...       # ~180 MB (stored once)

oci-infra/
├── shared/
│   └── .terraform.lock.hcl         # ~2 KB
├── vm-amd/
│   └── .terraform.lock.hcl         # ~2 KB
└── vm-arm/
    └── .terraform.lock.hcl         # ~2 KB

Total: ~180 MB (one copy) + ~6 KB lock files

Savings: ~360 MB eliminated. With 10 projects and 3 provider versions, the savings scale to multiple gigabytes.

6. CI/CD & Team Benefits

Scenario	Without Mirror	With Mirror
`terraform init` in CI	30-60s download	1-2s copy from cache
Air-gapped runner	Fails	Works
Reproducibility	Depends on registry uptime	100% offline
Repo size	Bloated with `.terraform/`	Clean, only `.tf` files
Parallel jobs	Each downloads separately	Shared system cache

7. Adding More Providers

To add another provider (e.g., hashicorp/random):

mkdir -p ~/.terraform.d/plugins-local/registry.terraform.io/hashicorp/random/3.6.0/linux_amd64
cd ~/.terraform.d/plugins-local/registry.terraform.io/hashicorp/random/3.6.0/linux_amd64
# Extract binary and rename:
mv terraform-provider-random_v3.6.0 terraform-provider-random_v3.6.0_x5

Update .terraformrc:

provider_installation {
  filesystem_mirror {
    path    = "/home/unknown/.terraform.d/plugins-local"
    include = [
      "oracle/oci",
      "hashicorp/random"
    ]
  }
  direct {
    exclude = [
      "oracle/oci",
      "hashicorp/random"
    ]
  }
}

8. Troubleshooting

"Installed provider (signed by HashiCorp partner...)"

Cause: .terraformrc not found or pattern doesn't match.

Fix: Ensure file is at ~/.terraformrc and include uses this format oracle/oci.

"fork/exec ... permission denied"

Cause: Terraform copied a .zip file instead of the extracted binary.

Fix: Remove .zip from the mirror directory; keep only the extracted binary.

"Provider not found in any of the search locations"

Cause: Wrong directory structure or binary naming.

Fix: Verify path ends in .../6.20.0/linux_amd64/terraform-provider-oci_v6.20.0_x5.

9. Quick Reference Commands

# Verify mirror structure
find ~/.terraform.d/plugins-local -type f

# Test if Terraform reads .terraformrc
TF_LOG=DEBUG terraform init 2>&1 | grep -i "filesystem_mirror\|Explicit provider"

# Force re-read backend and provider config
terraform init -reconfigure

# Clean project cache (safe — providers stay in ~/.terraform.d)
rm -rf .terraform/ .terraform.lock.hcl

Summary

File	Location	Purpose
`.terraformrc`	`~/.terraformrc`	Tells Terraform where to find local providers
Provider binaries	`~/.terraform.d/plugins-local/...`	The actual plugin executables
`provider.tf`	Inside each project	Declares which provider + version to use
`.terraform.lock.hcl`	Inside each project	Locks the provider version (tiny file)

Result: Your repositories stay clean, initialization is instant, and you are fully offline-capable.

Complete OCI Free Tier Infrastructure Guide Using Terraform - Part 03: Compute Layer (AMD & ARM)

sys-ronin — Fri, 07 Aug 2026 19:22:55 +0000

In Part 01 and Part 02 of this series, we configured local API keys, environment variables, created an offline provider mirror, built our remote state bucket, and provisioned the shared networking layer (VCN, public subnet, route tables, and security lists).

Now in Part 03, we complete the series by building the compute layer across two isolated directories:

~/oci-infra/vm-amd/ — x86 Architecture (VM.Standard.E2.1.Micro)
~/oci-infra/vm-arm/ — ARM Ampere Architecture (VM.Standard.A1.Flex configured with 1 OCPU and 6 GB RAM)

Both instances connect directly to the shared-public-subnet provisioned in Part 02 and persist state to their dedicated S3-compatible backend paths (vm-amd.tfstate and vm-arm.tfstate).

Section 1: AMD x86 Compute Instance (`~/oci-infra/vm-amd/`)

The AMD instance leverages the Always Free VM.Standard.E2.1.Micro shape (1 OCPU, 1 GB RAM, 50 GB boot volume).

1.1 Provider & Remote State (`provider.tf` & `backend.tf`)

provider.tf

terraform {
  required_version = ">= 1.5.0"
  required_providers {
    oci = {
      source  = "oracle/oci"
      version = "6.20.0"
    }
  }
}

provider "oci" {
  tenancy_ocid     = var.tenancy_ocid
  user_ocid        = var.user_ocid
  fingerprint      = var.fingerprint
  private_key_path = var.private_key_path
  region           = var.region
}

backend.tf

terraform {
  backend "s3" {
    bucket = "terraform-states"
    key    = "vm-amd.tfstate"
    region = "ap-hyderabad-1"
    endpoints = {
      s3 = "https://axjetxazylvl.compat.objectstorage.ap-hyderabad-1.oraclecloud.com"
    }

    skip_region_validation      = true
    skip_credentials_validation = true
    skip_metadata_api_check     = true
    skip_requesting_account_id  = true
    skip_s3_checksum            = true
    use_path_style              = true
  }
}

1.2 Data Resources (`data.tf`)

# Fetch availability domains
data "oci_identity_availability_domains" "ads" {
  compartment_id = var.tenancy_ocid
}

locals {
  first_ad = data.oci_identity_availability_domains.ads.availability_domains[0].name
}

# Image lookup for Oracle Linux 9 on x86_64
data "oci_core_images" "ol9" {
  compartment_id           = var.compartment_id
  operating_system         = "Oracle Linux"
  operating_system_version = "9"
  shape                    = "VM.Standard.E2.1.Micro"
  sort_by                  = "TIMECREATED"
  sort_order               = "DESC"
}

# Network lookup: find the shared subnet by display name
data "oci_core_subnets" "shared" {
  compartment_id = var.compartment_id

  filter {
    name   = "display_name"
    values = ["shared-public-subnet"]
  }
}

1.3 Variables (`variables.tf`)

variable "tenancy_ocid" {
  description = "OCID of the tenancy"
  type        = string
}

variable "user_ocid" {
  description = "OCID of the user"
  type        = string
}

variable "fingerprint" {
  description = "API key fingerprint"
  type        = string
}

variable "private_key_path" {
  description = "Path to the private API key"
  type        = string
}

variable "region" {
  description = "OCI region"
  type        = string
}

variable "compartment_id" {
  description = "OCID of the compartment"
  type        = string
}

variable "ssh_public_key_path" {
  description = "Path to SSH public key"
  type        = string
}

1.4 Resource Definition (`main.tf`)

locals {
  ssh_private_key_path = trimsuffix(pathexpand(var.ssh_public_key_path), ".pub")
}

resource "oci_core_instance" "amd" {
  availability_domain = local.first_ad
  compartment_id      = var.compartment_id
  display_name        = "amd-vm"
  shape               = "VM.Standard.E2.1.Micro"

  source_details {
    source_type             = "image"
    source_id               = data.oci_core_images.ol9.images[0].id
    boot_volume_size_in_gbs = 50
  }

  create_vnic_details {
    subnet_id        = data.oci_core_subnets.shared.subnets[0].id
    display_name     = "amd-vm-vnic"
    assign_public_ip = true
  }

  metadata = {
    ssh_authorized_keys = file(pathexpand(var.ssh_public_key_path))
  }

  preserve_boot_volume = false
}

1.5 Outputs (`outputs.tf`)

output "instance_id" {
  value = oci_core_instance.amd.id
}

output "public_ip" {
  value = oci_core_instance.amd.public_ip
}

output "ssh_command" {
  value = "ssh -i ${local.ssh_private_key_path} opc@${oci_core_instance.amd.public_ip}"
}

Section 2: ARM Ampere Flex Compute Instance (`~/oci-infra/vm-arm/`)

The ARM Ampere instance utilizes VM.Standard.A1.Flex configured explicitly with 1 OCPU and 6 GB RAM.

2.1 Provider & Remote State (`provider.tf` & `backend.tf`)

provider.tf

terraform {
  required_version = ">= 1.5.0"
  required_providers {
    oci = {
      source  = "oracle/oci"
      version = "6.20.0"
    }
  }
}

provider "oci" {
  tenancy_ocid     = var.tenancy_ocid
  user_ocid        = var.user_ocid
  fingerprint      = var.fingerprint
  private_key_path = var.private_key_path
  region           = var.region
}

backend.tf

terraform {
  backend "s3" {
    bucket = "terraform-states"
    key    = "vm-arm.tfstate"
    region = "ap-hyderabad-1"
    endpoints = {
      s3 = "https://axjetxazylvl.compat.objectstorage.ap-hyderabad-1.oraclecloud.com"
    }

    skip_region_validation      = true
    skip_credentials_validation = true
    skip_metadata_api_check     = true
    skip_requesting_account_id  = true
    skip_s3_checksum            = true
    use_path_style              = true
  }
}

2.2 Data Resources (`data.tf`)

# -----------------------------------------------------------------------------
# Availability Domains
# -----------------------------------------------------------------------------
data "oci_identity_availability_domains" "ads" {
  compartment_id = var.tenancy_ocid
}

locals {
  first_ad = data.oci_identity_availability_domains.ads.availability_domains[0].name
}

# -----------------------------------------------------------------------------
# Image Lookup: Oracle Linux 9 for A1.Flex (ARM)
# -----------------------------------------------------------------------------
data "oci_core_images" "ol9" {
  compartment_id           = var.compartment_id
  operating_system         = "Oracle Linux"
  operating_system_version = "9"
  shape                    = "VM.Standard.A1.Flex"
  sort_by                  = "TIMECREATED"
  sort_order               = "DESC"
}

# -----------------------------------------------------------------------------
# Network Discovery: Find the shared subnet by name
# -----------------------------------------------------------------------------
data "oci_core_subnets" "shared" {
  compartment_id = var.compartment_id

  filter {
    name   = "display_name"
    values = ["shared-public-subnet"]
  }
}

2.3 Variables (`variables.tf`)

variable "tenancy_ocid" {
  description = "OCID of the tenancy"
  type        = string
}

variable "user_ocid" {
  description = "OCID of the user"
  type        = string
}

variable "fingerprint" {
  description = "API key fingerprint"
  type        = string
}

variable "private_key_path" {
  description = "Path to the private API key"
  type        = string
}

variable "region" {
  description = "OCI region"
  type        = string
}

variable "compartment_id" {
  description = "OCID of the compartment to create resources in"
  type        = string
}

variable "ssh_public_key_path" {
  description = "Path to the SSH public key for instance access"
  type        = string
}

2.4 Resource Definition (`main.tf`)

locals {
  ssh_private_key_path = trimsuffix(pathexpand(var.ssh_public_key_path), ".pub")
}

resource "oci_core_instance" "arm" {
  availability_domain = local.first_ad
  compartment_id      = var.compartment_id
  display_name        = "arm-vm"
  shape               = "VM.Standard.A1.Flex"

  shape_config {
    ocpus         = 1
    memory_in_gbs = 6
  }

  source_details {
    source_type             = "image"
    source_id               = data.oci_core_images.ol9.images[0].id
    boot_volume_size_in_gbs = 50
  }

  create_vnic_details {
    subnet_id        = data.oci_core_subnets.shared.subnets[0].id
    display_name     = "arm-vm-vnic"
    assign_public_ip = true
  }

  metadata = {
    ssh_authorized_keys = file(pathexpand(var.ssh_public_key_path))
  }

  preserve_boot_volume = false
}

2.5 Outputs (`outputs.tf`)

output "instance_id" {
  description = "OCID of the ARM instance"
  value       = oci_core_instance.arm.id
}

output "instance_name" {
  description = "Display name of the ARM instance"
  value       = oci_core_instance.arm.display_name
}

output "shape" {
  description = "Shape of the ARM instance"
  value       = oci_core_instance.arm.shape
}

output "ocpus" {
  description = "Configured OCPUs"
  value       = oci_core_instance.arm.shape_config[0].ocpus
}

output "memory_in_gbs" {
  description = "Configured memory in GBs"
  value       = oci_core_instance.arm.shape_config[0].memory_in_gbs
}

output "availability_domain" {
  description = "Availability domain of the ARM instance"
  value       = oci_core_instance.arm.availability_domain
}

output "private_ip" {
  description = "Private IP address of the ARM instance"
  value       = oci_core_instance.arm.private_ip
}

output "public_ip" {
  description = "Public IP address of the ARM instance"
  value       = oci_core_instance.arm.public_ip
}

output "subnet_id" {
  description = "OCID of the attached subnet"
  value       = oci_core_instance.arm.create_vnic_details[0].subnet_id
}

output "image_id" {
  description = "OCID of the boot image used"
  value       = oci_core_instance.arm.source_details[0].source_id
}

output "ssh_username" {
  description = "Default SSH username"
  value       = "opc"
}

output "ssh_command" {
  description = "SSH command to connect to the instance"
  value       = "ssh -i ${local.ssh_private_key_path} opc@${oci_core_instance.arm.public_ip}"
}

Section 3: Deployment & Verification Workflow

3.1 Deploying the AMD x86 Workload

cd ~/oci-infra/vm-amd/
terraform init
terraform plan
terraform apply -auto-approve

3.2 Deploying the ARM Ampere Workload

cd ~/oci-infra/vm-arm/
terraform init
terraform plan
terraform apply -auto-approve

3.3 Accessing the Instances

Upon completion, retrieve the SSH commands from the output variables or run:

# SSH into AMD Instance
ssh -i ~/.ssh/oci_vm_key opc@<AMD_PUBLIC_IP>

# SSH into ARM Instance
ssh -i ~/.ssh/oci_vm_key opc@<ARM_PUBLIC_IP>

Series Conclusion

You have successfully built an automated, production-grade cloud foundation on Oracle Cloud Infrastructure:

Part 01: Setup environment authentication, API keys, offline provider mirror, and remote state bucket (terraform-states).
Part 02: Provisioned core networking (main-vcn, shared-public-subnet, internet gateway, security list) and application object storage.
Part 03: Deployed modular AMD (VM.Standard.E2.1.Micro) and ARM (VM.Standard.A1.Flex with 1 OCPU and 6 GB RAM) compute instances attached to the shared subnet and state backends.

Complete OCI Free Tier Infrastructure Guide Using Terraform - Part 02: Shared Architecture Layer

sys-ronin — Fri, 07 Aug 2026 19:21:24 +0000

In Part 01 of this guide, we configured local keys, exported shell variables, created an offline provider mirror, and established our remote state bucket.

Now in Part 02, we build the foundation of our cloud environment in ~/oci-infra/shared/. This shared architecture layer provisions the core Virtual Cloud Network (VCN), internet gateway, public subnet, security rules, standard Object Storage bucket, and S3-compatible remote state backend configuration [cite: 2, 3].

1. Provider Configuration (`provider.tf`)

Defines the required Terraform engine and provider versions [cite: 5], along with authentication credentials passed via shell environment variables [cite: 5, 6].

terraform {
  required_version = ">= 1.5.0"
  required_providers {
    oci = {
      source  = "oracle/oci"
      version = "6.20.0"
    }
  }
}

provider "oci" {
  tenancy_ocid     = var.tenancy_ocid
  user_ocid        = var.user_ocid
  fingerprint      = var.fingerprint
  private_key_path = var.private_key_path
  region           = var.region
}

Terraform Engine: Requires version >= 1.5.0 [cite: 5].
OCI Provider: Pins the oracle/oci provider to version 6.20.0 [cite: 5].
Authentication: Uses API key configuration via tenancy OCID, user OCID, fingerprint, private key path, and region [cite: 5].

2. Environment Variables (`variables.tf`)

Defines the required input variables used to configure authentication and resource placement [cite: 6].

variable "tenancy_ocid" {
  description = "OCID of the tenancy"
  type        = string
}

variable "user_ocid" {
  description = "OCID of the user"
  type        = string
}

variable "fingerprint" {
  description = "API key fingerprint"
  type        = string
}

variable "private_key_path" {
  description = "Path to the private API key"
  type        = string
}

variable "region" {
  description = "OCI region"
  type        = string
}

variable "compartment_id" {
  description = "OCID of the compartment to create resources in"
  type        = string
}

3. Remote State Backend (`backend.tf`)

Configures Terraform to store state remotely inside an OCI Object Storage bucket using the S3-compatible API [cite: 2].

terraform {
  backend "s3" {
    bucket = "terraform-states"
    key    = "shared.tfstate"
    region = "ap-hyderabad-1"
    endpoints = {
      s3 = "https://axjetxazylvl.compat.objectstorage.ap-hyderabad-1.oraclecloud.com"
    }

    skip_region_validation      = true
    skip_credentials_validation = true
    skip_metadata_api_check     = true
    skip_requesting_account_id  = true
    skip_s3_checksum            = true
    use_path_style              = true
  }
}

Bucket & State Key: Stores the state in terraform-states under shared.tfstate [cite: 2].
S3 Compatibility Endpoint: Points directly to OCI's native S3 API endpoint (https://axjetxazylvl.compat.objectstorage.ap-hyderabad-1.oraclecloud.com) [cite: 2].
AWS S3 Overrides: Forces path-style addressing (use_path_style = true) and disables standard AWS-specific checks (checksums, metadata API, credentials validation) to maintain OCI compatibility [cite: 2].

4. Main Infrastructure Resources (`main.tf`)

Contains resources for the Virtual Cloud Network (VCN), networking gateway, security list, public subnet, and storage bucket [cite: 3].

# -----------------------------------------------------------------------------
# Virtual Cloud Network
# -----------------------------------------------------------------------------
resource "oci_core_vcn" "main" {
  compartment_id = var.compartment_id
  cidr_block     = "10.0.0.0/16"
  display_name   = "main-vcn"
  dns_label      = "mainvcn"
}

# -----------------------------------------------------------------------------
# Internet Gateway
# -----------------------------------------------------------------------------
resource "oci_core_internet_gateway" "main" {
  compartment_id = var.compartment_id
  vcn_id         = oci_core_vcn.main.id
  display_name   = "main-igw"
}

# -----------------------------------------------------------------------------
# Route Table
# -----------------------------------------------------------------------------
resource "oci_core_route_table" "public" {
  compartment_id = var.compartment_id
  vcn_id         = oci_core_vcn.main.id
  display_name   = "public-route-table"

  route_rules {
    destination       = "0.0.0.0/0"
    destination_type  = "CIDR_BLOCK"
    network_entity_id = oci_core_internet_gateway.main.id
  }
}

# -----------------------------------------------------------------------------
# Security List
# -----------------------------------------------------------------------------
resource "oci_core_security_list" "public" {
  compartment_id = var.compartment_id
  vcn_id         = oci_core_vcn.main.id
  display_name   = "public-security-list"

  # SSH from anywhere
  ingress_security_rules {
    protocol    = "6" # TCP
    source      = "0.0.0.0/0"
    source_type = "CIDR_BLOCK"
    tcp_options {
      min = 22
      max = 22
    }
  }

  # ICMP for MTU path discovery (required by OCI)
  ingress_security_rules {
    protocol    = "1" # ICMP
    source      = "0.0.0.0/0"
    source_type = "CIDR_BLOCK"
    icmp_options {
      type = 3
      code = 4
    }
  }

  # Allow ping (ICMP echo request/reply)
  ingress_security_rules {
    protocol    = "1" # ICMP
    source      = "0.0.0.0/0"
    source_type = "CIDR_BLOCK"
    icmp_options {
      type = 8  # Echo Request
      code = -1 # All codes
    }
  }

  # Allow all outbound
  egress_security_rules {
    protocol    = "all"
    destination = "0.0.0.0/0"
  }
}

# -----------------------------------------------------------------------------
# Subnet
# -----------------------------------------------------------------------------
resource "oci_core_subnet" "public" {
  compartment_id             = var.compartment_id
  vcn_id                     = oci_core_vcn.main.id
  cidr_block                 = "10.0.0.0/24"
  display_name               = "shared-public-subnet"
  dns_label                  = "public"
  route_table_id             = oci_core_route_table.public.id
  security_list_ids          = [oci_core_security_list.public.id]
  prohibit_public_ip_on_vnic = false
}

# -----------------------------------------------------------------------------
# Object Storage Bucket
# -----------------------------------------------------------------------------
resource "oci_objectstorage_bucket" "infra_data" {
  compartment_id = var.compartment_id
  namespace      = "axjetxazylvl"
  name           = "infra-data"
  storage_tier   = "Standard"
  access_type    = "NoPublicAccess"
}

Resource Breakdown

VCN (oci_core_vcn.main): Named main-vcn with CIDR 10.0.0.0/16 and internal DNS label mainvcn [cite: 3].
Internet Gateway (oci_core_internet_gateway.main): Named main-igw, allowing outbound internet connection for instances [cite: 3].
Route Table (oci_core_route_table.public): Directs default outbound traffic (0.0.0.0/0) through the Internet Gateway [cite: 3].
Security List (oci_core_security_list.public):
- TCP port 22 (SSH) allowed from anywhere (0.0.0.0/0) [cite: 3].
- ICMP Type 3 Code 4 enabled (required by OCI for path MTU discovery) [cite: 3].
- ICMP Type 8 (Echo Request / Ping) enabled [cite: 3].
- Full egress traffic (0.0.0.0/0) allowed [cite: 3].
Public Subnet (oci_core_subnet.public): CIDR block 10.0.0.0/24, attached to the public route table and public security list, with public IPs allowed (prohibit_public_ip_on_vnic = false) [cite: 3].
Object Storage Bucket (oci_objectstorage_bucket.infra_data): Named infra-data, using namespace axjetxazylvl, standard storage tier, and NoPublicAccess [cite: 3].

5. Architectural Outputs (`outputs.tf`)

Exposes critical resource IDs and attributes for reference by isolated sub-modules (such as compute instances) [cite: 4].

output "vcn_id" {
  description = "OCID of the created VCN"
  value       = oci_core_vcn.main.id
}

output "vcn_cidr" {
  description = "CIDR block of the VCN"
  value       = oci_core_vcn.main.cidr_block
}

output "vcn_dns_label" {
  description = "DNS label of the VCN"
  value       = oci_core_vcn.main.dns_label
}

output "subnet_id" {
  description = "OCID of the public subnet"
  value       = oci_core_subnet.public.id
}

output "subnet_cidr" {
  description = "CIDR block of the public subnet"
  value       = oci_core_subnet.public.cidr_block
}

output "subnet_dns_label" {
  description = "DNS label of the public subnet"
  value       = oci_core_subnet.public.dns_label
}

output "internet_gateway_id" {
  description = "OCID of the Internet Gateway"
  value       = oci_core_internet_gateway.main.id
}

output "security_list_id" {
  description = "OCID of the Security List"
  value       = oci_core_security_list.public.id
}

output "infra_bucket_name" {
  description = "Name of the application bucket"
  value       = oci_objectstorage_bucket.infra_data.name
}

output "infra_bucket_namespace" {
  description = "Namespace of the application bucket"
  value       = oci_objectstorage_bucket.infra_data.namespace
}

output "infra_bucket_endpoint" {
  description = "S3-compatible endpoint for the application bucket"
  value       = "https://${oci_objectstorage_bucket.infra_data.namespace}.compat.objectstorage.${var.region}.oraclecloud.com"
}

6. Execution Workflow

From inside the ~/oci-infra/shared/ directory, run:

# Initialize using the local provider mirror and remote S3 state backend
terraform init

# Review execution plan
terraform plan

# Apply infrastructure changes
terraform apply

Next Steps

With your shared core networking, security rules, and state storage provisioned, your tenancy foundation is complete.

In Part 03, we will provision the compute layer—deploying Always Free x86 (vm-amd) and ARM Ampere (vm-arm) instances connected directly to shared-public-subnet.

Complete OCI Free Tier Infrastructure Guide Using Terraform - Part 01: Setup & Local Provider Mirror

sys-ronin — Fri, 07 Aug 2026 19:11:40 +0000

Setting up Oracle Cloud Infrastructure (OCI) using Terraform gives you an automated, reproducible "Always Free" cloud environment. However, managing backend state safely and dealing with air-gapped or restricted provider installations can introduce friction.

In Part 01 of this series, we walk through configuring local credentials, OCI API integration, an S3-compatible backend for state management, an air-gapped local Terraform provider mirror, and a modular folder structure.

Prerequisites

A local Linux machine (Debian/Ubuntu preferred) or WSL environment.
An active Oracle Cloud Infrastructure (OCI) Free Tier account.
OpenSSL, SSH, and Terraform installed.

Phase 1: Local Machine Setup

Generate local cryptographic keys required for SSH access to your instances and secure API authentication with OCI.

1.1 Generate SSH Key Pair (ED25519)

Generate a high-security ED25519 key pair without a passphrase for non-interactive infrastructure management:

ssh-keygen -t ed25519 -N "" -C "oci_vm_key" -f ~/.ssh/oci_vm_key

This generates two files:

Private key: ~/.ssh/oci_vm_key (keep safe)
Public key: ~/.ssh/oci_vm_key.pub

1.2 Create OCI API Key Directory

Restrict permissions on the configuration directory to preserve security standards:

mkdir -p ~/.oci
chmod 700 ~/.oci

1.3 Generate OCI API Key Pair (RSA 4096)

OCI requires an RSA 4096-bit key pair for programmatic API authentication:

# Generate private key
openssl genrsa -out ~/.oci/oci.pem 4096

# Generate public key
openssl rsa -pubout -in ~/.oci/oci.pem -out ~/.oci/oci_public.pem

# Secure permissions (OCI rejects keys with permissions broader than 600)
chmod 600 ~/.oci/oci.pem

1.4 Generate Key Fingerprint

Extract the MD5 fingerprint of your public key. You will need this to verify API connectivity in the OCI Console:

openssl rsa -pubout -in ~/.oci/oci.pem -outform DER | openssl md5 -c

💡 Output Example:

MD5(stdin)= 57:0d:ea:8c:07:11:22:33:44:55:66:77:88:99:aa:bb

Phase 2: OCI Console Configuration

2.1 Upload API Public Key

Log into your OCI Console.
Navigate to Profile (top right icon) → My Profile.
Under Resources (bottom left), click API Keys → Add API Key.
Select Paste a Public Key.
Output the contents of ~/.oci/oci_public.pem and paste them into the text box:

   cat ~/.oci/oci_public.pem

Click Add.

🔒 Save Configuration Details:

A Configuration File Preview popup will appear. Copy these values—they contain your user OCID, tenancy OCID, fingerprint, and your home region (e.g., ap-hyderabad-1).

2.2 Retrieve Object Storage Namespace

Your Object Storage namespace is a unique, system-generated string tied to your tenant. Retrieve it using the OCI CLI or Cloud Shell:

oci os ns get

Expected JSON output:

{
  "data": "axjetxbzylvl"
}

2.3 Create the Terraform Remote State Bucket

Store your .tfstate files remotely in OCI Object Storage:

Open Object Storage → Buckets in the OCI Console.
Click Create Bucket.
Fill in the parameters:
- Bucket Name: terraform-states
- Default Storage Tier: Standard
- Visibility: Private
- Region: Select your Home Region
Click Create.

2.4 Generate S3-Compatible Credentials

OCI Object Storage provides an S3-compatible API endpoint, allowing you to use standard S3 backend configurations in Terraform.

Go to Profile → My Profile → Customer Secret Keys.
Click Generate Secret Key.
Enter a display name: terraform-backend.
Click Generate Secret Key.

⚠️ Important: Copy and save the generated Secret Key immediately. It will never be displayed again.

Access Key: Visible in the Customer Secret Keys table (e.g., f4068126c6fd14c08a121d17396u317e6144e6a2)

Secret Key: Copied from the modal dialog.

Phase 3: Shell Environment Setup (`~/.bashrc`)

To prevent hardcoding sensitive credentials inside your Terraform code, export them as environment variables.

Add the following block to the bottom of your ~/.bashrc file (replace placeholders with your actual OCIDs, keys, and paths):

# =============================================================================
# OCI Provider Credentials
# =============================================================================
export TF_VAR_tenancy_ocid="ocid1.tenancy.oc1..aaaaaaaa..."
export TF_VAR_user_ocid="ocid1.user.oc1..aaaaaaaa..."
export TF_VAR_fingerprint="57:0d:ea:8c:07:..."
export TF_VAR_private_key_path="$HOME/.oci/oci.pem"
export TF_VAR_region="ap-hyderabad-1"
export TF_VAR_compartment_id="ocid1.tenancy.oc1..aaaaaaaa..."

# =============================================================================
# S3-Compatible Backend Credentials (OCI Object Storage S3 API)
# =============================================================================
export AWS_ACCESS_KEY_ID="f4068126c6..."
export AWS_SECRET_ACCESS_KEY="YOUR_SECRET_KEY_HERE"
export AWS_REQUEST_CHECKSUM_CALCULATION=when_required

# =============================================================================
# Backend Configuration Variables
# =============================================================================
export TF_VAR_backend_bucket="terraform-states"
export TF_VAR_backend_namespace="axjftxazylvl"
export TF_VAR_backend_region="ap-hyderabad-1"

# =============================================================================
# SSH Key for VM Provisioning
# =============================================================================
export TF_VAR_ssh_public_key_path="$HOME/.ssh/oci_vm_key.pub"

# =============================================================================
# OCI CLI Path & Autocomplete (Adjust path to your user home)
# =============================================================================
export PATH="$HOME/bin:$PATH"
if [[ -f "$HOME/lib/oracle-cli/lib/python3.13/site-packages/oci_cli/bin/oci_autocomplete.sh" ]]; then
  source "$HOME/lib/oracle-cli/lib/python3.13/site-packages/oci_cli/bin/oci_autocomplete.sh"
fi

Apply the environment changes:

source ~/.bashrc

Phase 4: Offline / Local Provider Mirror Configuration

If you want fast execution or operate in an environment with limited internet access, you can mirror the official OCI provider locally.

4.1 Create Directory Structure

Build the target plugin directory structure expected by Terraform for oracle/oci version 6.20.0:

mkdir -p ~/.terraform.d/plugins-local/registry.terraform.io/oracle/oci/6.20.0/linux_amd64

4.2 Download and Unpack Provider Binary

Download terraform-provider-oci_6.20.0_linux_amd64.zip directly from the HashiCorp or Oracle releases registry, place it in the created path, and unpack it:

cd ~/.terraform.d/plugins-local/registry.terraform.io/oracle/oci/6.20.0/linux_amd64

# Unzip binary package
unzip terraform-provider-oci_6.20.0_linux_amd64.zip

# Rename provider binary to append protocol version target
mv terraform-provider-oci_v6.20.0 terraform-provider-oci_v6.20.0_x5

# Clean up archive
rm terraform-provider-oci_6.20.0_linux_amd64.zip

Verify that your local mirror directory tree matches this structure:

~/.terraform.d/
└── plugins-local
    └── registry.terraform.io
        └── oracle
            └── oci
                └── 6.20.0
                    └── linux_amd64
                        └── terraform-provider-oci_v6.20.0_x5

4.3 Configure Global Provider Installation (`~/.terraformrc`)

Create a global CLI configuration file at ~/.terraformrc to force Terraform to load the OCI provider directly from your filesystem mirror instead of downloading it during terraform init:

provider_installation {
  filesystem_mirror {
    path    = "/home/YOUR_USER_NAME/.terraform.d/plugins-local"
    include = ["oracle/oci"]
  }
  direct {
    exclude = ["oracle/oci"]
  }
}

⚠️ Note: Replace /home/YOUR_USER_NAME/ with the absolute path to your home directory (Terraform does not expand ~ inside .terraformrc).

Phase 5: Project Directory Architecture

To manage networking and compute instances independently without creating monolithic state files, isolate components into modular subdirectories:

Create the workspace structure:

mkdir -p ~/oci-infra/{shared,vm-amd,vm-arm}

~/oci-infra/
├── shared/          # VCN, subnets, IGW, route tables, security lists, buckets
│   ├── backend.tf
│   ├── provider.tf
│   ├── variables.tf
│   ├── main.tf
│   └── outputs.tf
├── vm-amd/          # Always Free x86 Instance (E2.1.Micro + Oracle Linux 9)
│   ├── backend.tf
│   ├── provider.tf
│   ├── variables.tf
│   ├── data.tf
│   ├── main.tf
│   └── outputs.tf
└── vm-arm/          # Always Free ARM Instance (A1.Flex + Oracle Linux 9)
    ├── backend.tf
    ├── provider.tf
    ├── variables.tf
    ├── data.tf
    ├── main.tf
    └── outputs.tf

Next Steps

With your API keys generated, environment variables configured, local provider mirrored, and project folders structured, your system is ready.

In Part 02, we will write the HCL declarations for the shared/ module—building a Virtual Cloud Network (VCN), public subnets, internet gateways, and locking down security lists within OCI Always Free limits.

Prior Art as Code: A practical guide to protecting open source innovations

sys-ronin — Wed, 01 Jul 2026 13:06:53 +0000

Prior Art as Code: A Practical Guide

Protect your open source project from patent trolls by embedding prior art in your repository

1. What Is Prior Art?

Prior art is any public evidence that an invention already exists. Under US law (35 U.S.C. § 102(a)(1)), an invention cannot be patented if it was "described in a printed publication" before the filing date. Under European law (EPC Article 54(2)), the state of the art includes "everything made available to the public" before filing. The EPO's G 1/23 decision (2025) clarified that public availability alone is sufficient – no reproducibility required.

Prior art proves the invention was already known. That makes any later patent invalid.

2. Why Prior Art Matters for Open Source

Open source projects are prime targets for patent trolls because:

Threat	Why It Matters
Code is public	Trolls can scan for novel inventions
No patent budget	Most open source projects cannot afford to file or defend patents
No legal team	Individual contributors are vulnerable to lawsuits

The solution is prior art. It costs nothing, requires no legal fees, and blocks patents before they are filed.

3. The Problem with Traditional Defensive Publications

Problem	Why It Fails
Separate from code	Hard to find, easy to ignore
Expensive	Many services charge fees (IP.com, etc.)
Static	Rarely updated
Not enabling	Vague descriptions do not convince examiners
Unverifiable	No working code to prove the invention works

Traditional defensive publications are weak prior art.

4. Prior Art as Code: A Better Approach

Prior art as code embeds prior art directly in your source repository. It provides:

Feature	Benefit
Integrated with code	Documents live alongside the implementation
Timestamped by Git	Immutable proof of publication date
Enabling disclosure	Enough detail to re‑implement the invention
Verifiable	Working code is the evidence
Free	Public repositories cost nothing
Searchable	Patent examiners can find it

This is stronger prior art. It is enabling, verifiable, and timestamped.

5. Example: Thought OS

Thought OS is a real open source project that uses this approach. Its repository contains a comprehensive prior art document with various disclosed concepts, including:

UUID permanence (items keep identity across renames)
Hardware binding without TPM
Resurrection from Git history
Active cache validation

Each concept is described in its own separate document, making it easy to update, reference, and understand individually. The main document indexes them all. This modular approach is recommended for complex projects.

For reference: https://github.com/sjyotis/thought-os

6. The Prior Art Document Itself Is Sufficient

The prior art document alone, with working code and a timestamp, is sufficient to establish prior art and invalidate later patents. The law itself provides the protection – 35 U.S.C. § 102(a)(1) and EPC Article 54(2) invalidate any patent that claims an invention already disclosed.

7. How to Implement Prior Art as Code

Step 1: Identify Your Novel Inventions

Ask: "What would I be angry about if someone else patented?"

Step 2: Write an Enabling Description

Include:

Plain language summary
Technical specification (data structures, algorithms, protocols)
Code references (files and line numbers)
Diagrams (flowcharts, sequence diagrams)

Step 3: Create Prior Art Documents

For simple projects, a single PRIOR_ART_DISCLOSURE.md is enough. For complex projects with multiple independent features, create separate documents per concept in a docs/ folder (e.g., docs/resurrection-engine.md, docs/hardware-binding.md). Use a main PRIOR_ART_DISCLOSURE.md as an index linking to each.

Step 4: Timestamp with Git

Commit the documents with a message like docs: add prior art disclosure. The commit timestamp proves publication date.

Step 5: Link It in Your README

Make the prior art document easy to find. Patent examiners need to discover it.

Step 6: Publish Publicly

Push to a public repository (GitHub, GitLab, etc.). Public availability is what matters.

8. Suggested Platforms for Publication

Platform	Best For	Notes
GitHub	Source code + documents	The standard for open source; patent examiners search here
GitLab	Source code + documents	Alternative to GitHub; also searchable
SourceForge	Source code + documents	Legacy platform, still indexed
IP.com	Prior art submission	Paid service, submitted to patent offices
Zenodo	Document publication	Assigns DOI (persistent identifier)
arXiv	Technical papers	Academic-style prior art
Hacker News	Project announcements	Creates social timestamp
Dev.to	Technical articles	Searchable, indexed by Google

Best practice: Publish on GitHub + one other platform (e.g., Zenodo) for redundancy.

9. Optional: Patent‑Prohibiting License

While the prior art document alone is sufficient to invalidate later patents, you may choose to add an explicit patent‑prohibiting license. Such a license:

Explicitly forbids patenting of the disclosed concepts
Provides a separate legal basis (contract law) to challenge a patent
Sends a clear signal that the technology belongs to no one

It is optional. The prior art is the shield. The license is an extra lock on the gate.

10. Why Prior Art as Code Is Stronger

Aspect	Traditional Prior Art	Prior Art as Code
Cost	Paid	Free
Integration	Separate	Integrated with code
Timestamp	Manual	Git commits
Enabling	Often vague	Detailed, with code
Verifiable	Hard	Working code is evidence
Modularity	Single document	Separate files per concept

Prior art as code is stronger because it provides all the evidence needed.

11. Conclusion

Prior art as code is a free, effective way to protect open source projects from patents. It works by:

Establishing a public, timestamped, enabling disclosure
Referencing the actual working code

The prior art document itself is sufficient. The law (35 U.S.C. § 102(a)(1), EPC Article 54(2)) invalidates any later patent claiming the disclosed concepts. A patent‑prohibiting license is optional – it adds an extra layer but is not required.

Every open source project should consider prior art as code. It costs nothing. It blocks patents. It protects innovation.

sjyotis

June 2026

thought-os@protonmail.com

Prior Art: The data structure that shapes Thought OS

sys-ronin — Fri, 19 Jun 2026 12:19:47 +0000

The Three‑File Architecture

The Foundation of the Entire System

1. The Division

Every notebook repository contains exactly three JSON files:

structure.json – the notebook hierarchy: names, UUIDs, parent relationships, and references to notes and subnotebooks.
notes.json – content of regular notes, keyed by UUID.
files.json – content of file notes (any file type), also keyed by UUID.

This separation is the foundation upon which every other feature is built.

2. Why Three Files, Not One

A single file containing everything (structure and all content) would create a single point of change for any modification. Every note edit would require rewriting the entire file. Git would store a full new version each time, regardless of delta compression, because the file would be completely different.

By separating structure from content:

Renaming a notebook or moving a note changes only structure.json.
Editing a note changes only notes.json (or files.json).
Adding a file changes only files.json and structure.json (but structure is a small addition).

Each file evolves independently. Git stores deltas for each file separately, so a small change in notes.json results in a small delta. The repository size grows with the number of changes, not with the number of versions times the total size.

This is the primary mechanism that keeps the Git storage footprint low over years of use.

3. UUID as the Common Key

All three files use the same UUIDs to refer to notes and files.

structure.json contains notes entries with id fields.
notes.json has keys equal to those UUIDs.
files.json also uses the same UUIDs as keys.

When a note is created, a UUID is generated. That UUID is stored in structure.json (as part of the note’s entry) and also becomes a key in notes.json (or files.json). The two are linked by the UUID.

This allows the system to:

Load the structure without loading content.
Load a note’s content by looking up its UUID in the appropriate content file.
Load content for a list of notes without scanning the structure again.

Because the link is by UUID, the content files are simple dictionaries. No complex mapping is needed.

4. How This Enables Navigation

Navigation (home screen, notebook view, subnotebook view) requires only structure.json. The user sees a list of notes with titles, timestamps, and file indicators. None of that needs the actual content.

When the user opens a notebook, structure.json is read. The notes list is built from the notes array. The content of the notes is not loaded.
When the user scrolls through the list, only the structure.json data is used.
The lock button can unload structure.json when locking a notebook, freeing memory. The content files are not even loaded, so no memory is wasted.

If structure and content were combined, unlocking a notebook would load all content automatically, increasing memory footprint and startup time.

5. How This Enables Git History

Git commits record changes to these files individually. Because they are separate:

A commit that renames a note touches only structure.json. The content file remains unchanged.
A commit that edits a note touches only notes.json. The structure file remains unchanged.
A commit that deletes a note touches structure.json (to remove the entry) and the appropriate content file (to remove the mapping). The two changes are in separate files, but they are part of the same commit.

This separation means that when you view the history of a note, the git log command can be scoped to notes.json. It does not need to filter through commits that only changed structure. Conversely, activity view for a notebook (showing renames) can focus on structure.json.

The commit messages embed the UUID and the action. Git does not need to parse the file content to understand what changed; the metadata is in the message.

6. How This Enables Resurrection

Resurrection requires reconstructing an item from a past commit. Because structure and content are separate:

The structure at a given commit is retrieved from structure.json at that commit.
The content is retrieved from notes.json or files.json at the same commit.
The UUID links the two.

If the files were combined, reconstructing a single note would require loading the entire monolithic file and extracting the relevant parts. With separation, only the necessary parts are loaded: the structure entry for the note and its content entry.

The timeline engine uses this to reconstruct only the requested item, not the whole notebook.

7. How This Enables Precise Deletion with `git‑filter‑repo`

When erasing a note, git-filter-repo is told to operate only on structure.json, notes.json, and files.json. Because the content is separate from the structure:

Removing a note requires removing its entry from structure.json and its key from notes.json (or files.json). Both are in separate files.
The UUIDEraseFilter can target these specific files, leaving other files untouched.

If the data were combined, erasing a note would require rewriting a single large file, potentially affecting other notes in the same file. Because of the separation, the operation is scoped and safe.

8. How This Enables Restoration

Restoration is the inverse of deletion. When a note is restored:

The structure entry is added back to structure.json.
The content entry is added back to notes.json (or files.json).
The UUID is reused; no new ID is generated.

Because structure and content are separate, adding them back is a simple insertion. The restore process does not need to merge two different file formats; it just appends to the appropriate JSON dictionaries and writes the files.

9. How This Enables Memory Efficiency

When a notebook is unlocked:

structure.json is read and parsed. This gives the entire note list (titles, timestamps, etc.) without loading any content.
notes.json and files.json are not read until a note is viewed.

When a note is viewed:

The appropriate content file is read and parsed.
The entire dictionary is loaded, but only one note’s content is displayed.

When the user returns to the notebook list, the content dictionary can be discarded (in practice, it stays until the notebook is locked or the app exits, but it is not needed for the list). The structure remains in memory, but structure is small compared to content.

If structure and content were combined, unlocking a notebook would load all content automatically, consuming memory proportional to the total size of all notes.

10. How This Enables the Lock Button as Memory Manager

Locking a notebook discards:

The parsed structure.json (the note list).
The parsed notes.json and files.json (if they were loaded).
The encryption key.

Because structure and content are separate, locking can be selective. The system does not need to keep structure in memory once the notebook is locked; it can be reloaded from disk when unlocked again.

If structure and content were combined, locking would either have to keep the combined structure in memory (wasting memory) or discard it entirely (requiring a full reload on unlock, which would reload all content as well). The separation allows fine‑grained control.

11. How This Enables Git Delta Efficiency

Git stores each file independently. Because structure and content are separate:

structure.json changes frequently but remains small (a few kilobytes). Git stores deltas for it.
notes.json and files.json grow over time but change only when their corresponding notes are edited. Each edit produces a small delta (the change in the encrypted blob, which Git compresses further).

If all data were in one file, every edit would change the entire file. Even with delta compression, the first edit after a large addition would create a large delta because the file would shift. Separation prevents this.

12. How This Enables Deterministic UUID‑Level Synchronisation

The three‑file architecture is the foundation for the sync algorithm. Because each UUID has its own independent chain of commits grouped by UUID, the system can:

Collect commits per UUID without parsing content. The commit message contains the UUID, and the raw blobs of the three files are captured as they are.
Resolve conflicts by timestamp for each UUID independently. Because notes are stored as key‑value pairs, changes to different UUIDs never interfere with each other.
Replay winning commits by simply writing the raw encrypted blobs. Each commit is a complete snapshot of the three files. Writing the blobs overwrites only the changed UUID’s entry, leaving other UUIDs untouched.
Preserve non‑conflicting edits automatically. If one side added a note (UUID‑A) and the other side added a different note (UUID‑B), both chains are kept. The final state contains both notes.
Avoid merge commits entirely because the sync algorithm rebuilds history on an orphan branch, never creating merge commits.

If structure and content were combined, a single commit would contain changes to multiple UUIDs. Grouping by UUID would be impossible without parsing the entire file. Conflict resolution would require merging file contents, not just comparing timestamps. The sync algorithm would become as complex as Git’s own merge. The three‑file architecture makes UUID‑level sync possible and simple.

13. Why This Design Is the Foundation for Everything

Without this separation:

Navigation would require loading content.
Git history would be a single file’s history, making it impossible to separate structure changes from content changes.
Resurrection would require reconstructing a monolithic file.
Deletion with git-filter-repo would be imprecise and risk affecting unrelated data.
Restoration would be a full‑file rewrite.
Memory would be tied to total note count, not active use.
The lock button could not unload structure independently of content.
Git storage would grow much faster because each edit would rewrite the entire notebook state.
Synchronisation would be impossible without complex file‑level merging, and per‑item conflict resolution would not exist.

This separation is not an implementation detail. It is the central architectural decision that enables every other feature:

Navigation – uses structure only.
Git history – separate files mean separate history streams.
Resurrection – reconstruct by UUID from two separate files.
Filter‑repo deletion – target specific files, not the whole notebook.
Restoration – append to two separate files.
Memory efficiency – load structure without content, load content on demand.
Lock button – discard structure, content, and key independently.
Storage efficiency – small deltas for small changes.
Synchronisation – per‑UUID commit chains, timestamp‑based conflict resolution, linear history reconstruction.

Every feature you built rests on this single decision: keep the notebook’s blueprint separate from its contents, and link them by UUID. Without it, the system would be a conventional note‑taking app. With it, it becomes a versioned, memory‑efficient, resurrectable, securely erasable, and synchronisable knowledge base.

This is why the three‑file architecture is the most important part of the codebase. It is not merely a storage format; it is the enabling structure for everything that follows.

terminal-notes - github
sys_ronin@protonmail.com

sys-ronin

An example where AI/LLM is used to create an architecture under the architects strict instruction

sys-ronin — Tue, 09 Jun 2026 19:59:23 +0000

I am a 40 years old sysadmin with 25 years old system knowledge without any formal education (no cs degree) and no python experience.

It is happened when i tried to design my note taking applications architecture Where I with my lack of formal education took a different path for building that (architecture) using AI/LLM.

I accidentally built my own cognition just asking myself how i think. I just thought it will be a great idea if i follow my own thought process, how it remember everything without searching inside my head. Then later I found after a thorough research that it is something very rare incident, where i have designed an architecture what matches the theory of our human hippocampus.

Though i created it for myself but I realised It is worthy enough to share the artefact built by AI/LLM and the discovery of what AI/LLM can do when instructed precisely with all its power.

I found similarities where my every python modules works as various features, the notebook folder acts as the memory and the application as a whole works as the brain. Where it creates memory, remember memory, forgot memory, erase memory where uuid is used as engram.

As it is accidentally built with my own cognition design (just like everybody else, same human brain), I found it does not need any learning curve and really helpful for writing, where I don't have to fight with the application for its distraction during writing.

Some of its features:

Only python 3.13, git and an editor is needed.
No learning curve
Unlimited notebooks/notes/files
Temporal Search
Git is used as item level versioning
AES-GCM encryption
Hardware bound movable vault without TPM
USB drive can be used as vault.
UI disappears while using
Free conflict free sync using github
App, Data and Keys can live separately

The AI/LLM development methodology is not documented for its vastness.

terminal-notes - github
sys_ronin@protonmail.com

The repo is published as "prior art"

sys-ronin

DEV Community: sys-ronin

AdventureWorks SQL Server with Docker and DBeaver Keystore Helper

The Goal

What I Built

The Bugs That Weren't in the Tutorial

1. Permission denied on entrypoint.sh

2. "Access is denied" on master.mdf

3. sqlcmd v18 won't connect without -C

4. DBeaver's JDBC driver demanded a keystore

DBeaver Connection — The Exact Settings

Main Tab

Driver Properties Tab

If You Don't Want the Keystore Hack

The Repo

Quick Start

Repo Structure

What This Actually Demonstrates

The Files

[How to] Terraform Offline Provider Setup: Zero Downloads & Clean Repos with Local Mirrors (with script)

Terraform Offline Provider Setup Guide

Using .terraformrc + .terraform.d for Zero-Download, Repo-Clean Infrastructure

1. The Problem

2. The Solution

3. Directory Structure

Important Naming Rules

4. Step-by-Step Setup

Step 1: Create ~/.terraformrc

Step 2: Prepare the Mirror Directory

Step 3: Extract the Provider Binary

Step 4: Configure provider.tf in Your Project

Step 5: Initialize and Verify

5. Space Savings Breakdown

Before (Default Behavior)

After (Local Mirror)

6. CI/CD & Team Benefits

7. Adding More Providers

8. Troubleshooting

"Installed provider (signed by HashiCorp partner...)"

"fork/exec ... permission denied"

"Provider not found in any of the search locations"

9. Quick Reference Commands

Summary

Complete OCI Free Tier Infrastructure Guide Using Terraform - Part 03: Compute Layer (AMD & ARM)

Section 1: AMD x86 Compute Instance (~/oci-infra/vm-amd/)

1.1 Provider & Remote State (provider.tf & backend.tf)

1.2 Data Resources (data.tf)

1.3 Variables (variables.tf)

1.4 Resource Definition (main.tf)

1.5 Outputs (outputs.tf)

Section 2: ARM Ampere Flex Compute Instance (~/oci-infra/vm-arm/)

2.1 Provider & Remote State (provider.tf & backend.tf)

2.2 Data Resources (data.tf)

2.3 Variables (variables.tf)

2.4 Resource Definition (main.tf)

2.5 Outputs (outputs.tf)

Section 3: Deployment & Verification Workflow

3.1 Deploying the AMD x86 Workload

3.2 Deploying the ARM Ampere Workload

3.3 Accessing the Instances

Series Conclusion

Complete OCI Free Tier Infrastructure Guide Using Terraform - Part 02: Shared Architecture Layer

1. Provider Configuration (provider.tf)

2. Environment Variables (variables.tf)

3. Remote State Backend (backend.tf)

4. Main Infrastructure Resources (main.tf)

Resource Breakdown

5. Architectural Outputs (outputs.tf)

6. Execution Workflow

Next Steps

Complete OCI Free Tier Infrastructure Guide Using Terraform - Part 01: Setup & Local Provider Mirror

Prerequisites

Phase 1: Local Machine Setup

1.1 Generate SSH Key Pair (ED25519)

1.2 Create OCI API Key Directory

1.3 Generate OCI API Key Pair (RSA 4096)

1.4 Generate Key Fingerprint

Phase 2: OCI Console Configuration

2.1 Upload API Public Key

2.2 Retrieve Object Storage Namespace

2.3 Create the Terraform Remote State Bucket

Using `.terraformrc` + `.terraform.d` for Zero-Download, Repo-Clean Infrastructure

Step 1: Create `~/.terraformrc`

Step 4: Configure `provider.tf` in Your Project

Section 1: AMD x86 Compute Instance (`~/oci-infra/vm-amd/`)

1.1 Provider & Remote State (`provider.tf` & `backend.tf`)

1.2 Data Resources (`data.tf`)

1.3 Variables (`variables.tf`)

1.4 Resource Definition (`main.tf`)

1.5 Outputs (`outputs.tf`)

Section 2: ARM Ampere Flex Compute Instance (`~/oci-infra/vm-arm/`)

2.1 Provider & Remote State (`provider.tf` & `backend.tf`)

2.2 Data Resources (`data.tf`)

2.3 Variables (`variables.tf`)

2.4 Resource Definition (`main.tf`)

2.5 Outputs (`outputs.tf`)

1. Provider Configuration (`provider.tf`)

2. Environment Variables (`variables.tf`)

3. Remote State Backend (`backend.tf`)

4. Main Infrastructure Resources (`main.tf`)

5. Architectural Outputs (`outputs.tf`)

Phase 3: Shell Environment Setup (`~/.bashrc`)

4.3 Configure Global Provider Installation (`~/.terraformrc`)

7. How This Enables Precise Deletion with `git‑filter‑repo`