{"id":51309419,"url":"https://github.com/zxcvresque/oracle-freetier-instance-creation","last_synced_at":"2026-07-01T02:32:14.410Z","repository":{"id":364762762,"uuid":"1268685517","full_name":"zxcvresque/oracle-freetier-instance-creation","owner":"zxcvresque","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-14T11:35:37.000Z","size":2643,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T12:21:39.927Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zxcvresque.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-13T20:23:40.000Z","updated_at":"2026-06-14T11:35:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zxcvresque/oracle-freetier-instance-creation","commit_stats":null,"previous_names":["zxcvresque/oracle-freetier-instance-creation"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/zxcvresque/oracle-freetier-instance-creation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zxcvresque%2Foracle-freetier-instance-creation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zxcvresque%2Foracle-freetier-instance-creation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zxcvresque%2Foracle-freetier-instance-creation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zxcvresque%2Foracle-freetier-instance-creation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zxcvresque","download_url":"https://codeload.github.com/zxcvresque/oracle-freetier-instance-creation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zxcvresque%2Foracle-freetier-instance-creation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34990845,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-01T02:32:12.888Z","updated_at":"2026-07-01T02:32:14.319Z","avatar_url":"https://github.com/zxcvresque.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ☁️ Oracle Free Tier Instance Creation\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"Banner.png\" alt=\"Oracle Free Tier Instance Creation banner\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://docs.oracle.com/en-us/iaas/Content/FreeTier/freetier.htm\"\u003e\u003cimg src=\"https://img.shields.io/badge/OCI-Always_Free-F80000?style=for-the-badge\u0026logo=oracle\u0026logoColor=white\" alt=\"OCI Always Free\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://docs.oracle.com/en-us/iaas/Content/Compute/References/computeshapes.htm\"\u003e\u003cimg src=\"https://img.shields.io/badge/OCI_ARM_Shape-VM.Standard.A1.Flex-2E7D32?style=for-the-badge\" alt=\"OCI ARM shape: VM.Standard.A1.Flex\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Target-2_OCPU_%2F_12_GB-1565C0?style=for-the-badge\" alt=\"Target: 2 OCPU and 12 GB\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Notifications-Telegram_%7C_Discord_%7C_Email-7B1FA2?style=for-the-badge\" alt=\"Notifications: Telegram, Discord, and Email\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/zxcvresque/oracle-freetier-instance-creation?style=for-the-badge\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nAutomates repeated Oracle Cloud Infrastructure instance launch attempts until capacity becomes available.\n\n\u003e **Free Tier capacity:** Oracle currently documents up to **4 Ampere A1 OCPUs and 24 GB of memory total** across A1 instances in an Always Free tenancy. This project's updated default request is **2 OCPUs and 12 GB RAM**, because of a discrepancy with recent news related to new Free Tier limits for A1 instance capacities. See [Oracle OCI Free Tier documentation](https://docs.oracle.com/en-us/iaas/Content/FreeTier/freetier.htm) and the [Oracle Cloud Free Tier page](https://www.oracle.com/cloud/free/).\n\nThe supported targets are:\n\n- ARM: `VM.Standard.A1.Flex`, 2 OCPU, 12 GB RAM\n- AMD: `VM.Standard.E2.1.Micro`, 1 OCPU, 1 GB RAM\n\nThe script retries according to `REQUEST_WAIT_TIME_SECS`, writes detailed logs locally, and can send notifications through email, Discord, and Telegram.\n\n## 🧭 Contents\n\n[How It Works](#how-it-works) · [Prerequisites](#prerequisites) · [Installation](#installation) · [Configure](#configure-the-script) · [Start](#start-the-script) · [Notifications](#telegram-notifications) · [Environment Variables](#environment-variables) · [Troubleshooting](#troubleshooting) · [References](#references)\n\n## ⚙️ How It Works\n\n1. Loads your OCI API credentials and instance settings.\n2. Finds the requested availability domain, subnet, and image.\n3. Checks whether the target instance already exists.\n4. Attempts to launch the instance.\n5. Waits and retries when OCI reports temporary capacity or rate-limit errors.\n6. Writes instance details to `INSTANCE_CREATED` after success.\n\n## ✅ Prerequisites\n\nBefore starting, you need:\n\n- An Oracle Cloud account.\n- An Ubuntu machine on which to run the script.\n  - An existing Always Free `VM.Standard.E2.1.Micro` instance is recommended.\n  - When running outside OCI, you must provide an existing subnet OCID through `OCI_SUBNET_ID`.\n- An OCI API key and its configuration-file preview.\n\n  \u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eCreate an Oracle API key\u003c/strong\u003e\u003c/summary\u003e\n\n  1. Sign in to the [Oracle Cloud Console](https://cloud.oracle.com/).\n  2. Open **Profile** in the top-right corner.\n  3. Click your **email address**.\n  4. Open **Tokens \u0026 Keys**.\n  5. In the **API Keys** section, click **Add API Key**.\n  6. Select **Generate API Key Pair**.\n  7. Download the **Private Key**. Store it securely; the private key cannot be downloaded again later.\n  8. Download the **Public Key** if you want to retain a copy.\n  9. Click **Add**.\n  10. Copy the complete **Configuration File Preview** shown by Oracle.\n\n  You will use:\n\n  - The downloaded private key as `oci_api_private_key.pem`.\n  - The configuration-file preview as `oci_config`.\n\n  The preview should look similar to:\n\n  ```ini\n  [DEFAULT]\n  user=ocid1.user.oc1...\n  fingerprint=...\n  tenancy=ocid1.tenancy.oc1...\n  region=...\n  key_file=/home/ubuntu/oracle-freetier-instance-creation/oci_api_private_key.pem\n  ```\n\n  Update `key_file` so it contains the absolute path to your private key on the machine running this script.\n\n  \u003c/details\u003e\n\n- The availability domain that is eligible for Always Free resources, such as `AD-1`.\n\n## 📦 Installation\n\nSSH into the Ubuntu machine that will run the script:\n\n```bash\nssh ubuntu@YOUR_SERVER_IP\n```\n\nClone this repository and enter it:\n\n```bash\ngit clone https://github.com/zxcvresque/oracle-freetier-instance-creation.git\ncd oracle-freetier-instance-creation\nchmod +x setup_env.sh setup_init.sh\n```\n\n## 🔑 OCI Credentials\n\nCreate the private-key file:\n\n```bash\nnano oci_api_private_key.pem\n```\n\nPaste the downloaded private key, save it, then restrict access:\n\n```bash\nchmod 600 oci_api_private_key.pem\n```\n\nCreate the OCI configuration file:\n\n```bash\nnano oci_config\n```\n\nPaste Oracle's configuration-file preview. Ensure `key_file` uses the correct absolute path:\n\n```ini\nkey_file=/home/ubuntu/oracle-freetier-instance-creation/oci_api_private_key.pem\n```\n\nDo not commit `oci_api_private_key.pem`, `oci_config`, or populated secrets to Git.\n\n## 🛠️ Configure the Script\n\nRun the interactive configuration script:\n\n```bash\n./setup_env.sh\n```\n\nIt creates `oci.env` and asks for the instance settings and optional notification integrations.\n\nIf `oci.env` already exists, it is backed up as `oci.env.bak`.\n\nReview the generated file:\n\n```bash\nnano oci.env\n```\n\nAt minimum, verify:\n\n```env\nOCI_CONFIG=/home/ubuntu/oracle-freetier-instance-creation/oci_config\nOCT_FREE_AD=AD-1\nDISPLAY_NAME=my-arm-ubuntu-instance\nOCI_COMPUTE_SHAPE=VM.Standard.A1.Flex\nREQUEST_WAIT_TIME_SECS=60\nSSH_AUTHORIZED_KEYS_FILE=/home/ubuntu/oracle-freetier-instance-creation/id_rsa.pub\nOPERATING_SYSTEM=Canonical Ubuntu\nOS_VERSION=22.04\n```\n\nIf you run the script outside an OCI instance, also set:\n\n```env\nOCI_SUBNET_ID=ocid1.subnet...\n```\n\n## 🚀 Start the Script\n\nFor the first run:\n\n```bash\n./setup_init.sh\n```\n\nThe first run creates a Python virtual environment and installs dependencies. This can take several minutes on a small E2 instance.\n\nThe terminal prints a short result:\n\n- Successful startup: inspect `launch_instance.log` for retries.\n- Configuration error: inspect `ERROR_IN_CONFIG.log`.\n- Unexpected setup/runtime error: inspect `UNHANDLED_ERROR.log`.\n\nFor later runs, skip dependency installation:\n\n```bash\n./setup_init.sh rerun\n```\n\n## 🖥️ Run Inside tmux\n\nStart the script in a detached session named `oracle`:\n\n```bash\ntmux new-session -d -s oracle \"cd ~/oracle-freetier-instance-creation \u0026\u0026 ./setup_init.sh rerun\"\n```\n\nCheck the session:\n\n```bash\ntmux attach -t oracle\n```\n\nDetach without stopping it by pressing `Ctrl+B`, then `D`.\n\nStop the session and any remaining Python process:\n\n```bash\ntmux kill-session -t oracle\npkill -f \"python3 main.py\" 2\u003e/dev/null\n```\n\nPull updates and restart using the existing configuration:\n\n```bash\ncd ~/oracle-freetier-instance-creation\ngit pull origin main\ntmux new-session -d -s oracle \"cd ~/oracle-freetier-instance-creation \u0026\u0026 ./setup_init.sh rerun\"\n```\n\n## 📋 Logs\n\n| File | Purpose |\n| --- | --- |\n| `setup_and_info.log` | Tenancy, availability domain, subnet, image, and setup information. |\n| `launch_instance.log` | Launch attempts, retryable capacity errors, rate limits, and launch responses. |\n| `ERROR_IN_CONFIG.log` | Invalid or malformed `oci_config` and configuration values. |\n| `UNHANDLED_ERROR.log` | Unexpected errors that stop the script. |\n| `INSTANCE_CREATED` | Details of the successfully created or detected target instance. |\n\nFollow live launch attempts:\n\n```bash\ntail -f launch_instance.log\n```\n\n## ✈️ Telegram Notifications\n\n### 💬 Direct Messages\n\n1. Create a bot through `@BotFather` using `/newbot`.\n2. Obtain your Telegram user ID.\n3. Add the following to `oci.env`:\n\n```env\nTELEGRAM_TOKEN=your_bot_token\nTELEGRAM_USER_ID=your_user_id\n```\n\n### 🗂️ Group Log Topics\n\nCreate a Telegram forum group, add the bot as an administrator, and create two topics:\n\n- `launch_instance`: receives launch and retry logs.\n- `errors`: receives configuration and unhandled errors.\n\nConfigure them in `oci.env`:\n\n```env\nTELEGRAM_LOGS_ENABLED=True\nTELEGRAM_LOG_GROUP_ID=-100xxxxxxxxxx\nTELEGRAM_LOG_INTERVAL_SECS=60\nTELEGRAM_LOG_TOPIC_LAUNCH_INSTANCE=x \nTELEGRAM_LOG_TOPIC_ERRORS=x\n```\n\nTo find IDs using `@MissRose_bot`:\n\n- Add `@MissRose_bot` to the group and run `/id` inside a topic to get its topic ID.\n- Run `/id` in the group's **General** topic to get the group ID.\n\nAlternatively, send a message inside the topic and request:\n\n```bash\ncurl \"https://api.telegram.org/bot\u003cTELEGRAM_TOKEN\u003e/getUpdates\"\n```\n\nUse the returned `message_thread_id`.\n\n## 🔔 Other Notifications\n\n### 🟣 Discord\n\nCreate a Discord webhook and set:\n\n```env\nDISCORD_WEBHOOK=your_discord_webhook_url\n```\n\n### ✉️ Gmail\n\nEnable email notifications and use a Gmail app password:\n\n```env\nNOTIFY_EMAIL=True\nEMAIL=your_email@gmail.com\nEMAIL_PASSWORD=your_app_password\n```\n\n## 🧩 Environment Variables\n\n### 📌 Required\n\n| Variable | Description |\n| --- | --- |\n| `OCI_CONFIG` | Absolute path to the OCI configuration file. |\n| `OCT_FREE_AD` | Always Free availability domain. Separate multiple values with commas. |\n\n### 🖥️ Instance Settings\n\n| Variable | Description |\n| --- | --- |\n| `DISPLAY_NAME` | Instance display name. |\n| `OCI_COMPUTE_SHAPE` | `VM.Standard.A1.Flex` or `VM.Standard.E2.1.Micro`. |\n| `SECOND_MICRO_INSTANCE` | Set `True` when creating the second free Micro instance. |\n| `REQUEST_WAIT_TIME_SECS` | Delay between retryable launch attempts. |\n| `SSH_AUTHORIZED_KEYS_FILE` | Public SSH key path. A key pair is generated if it does not exist. |\n| `OCI_SUBNET_ID` | Existing subnet OCID. Required when the script cannot discover a subnet. |\n| `OCI_IMAGE_ID` | Optional exact image OCID. Overrides OS name and version selection. |\n| `OPERATING_SYSTEM` | Exact operating-system name used when selecting an image. |\n| `OS_VERSION` | Exact operating-system version used when selecting an image. |\n| `ASSIGN_PUBLIC_IP` | Set `true` to request an ephemeral public IP. |\n| `BOOT_VOLUME_SIZE` | Boot volume size in GB. Minimum is 50. |\n\n### 🔔 Notifications\n\n| Variable | Description |\n| --- | --- |\n| `NOTIFY_EMAIL` | Enables Gmail notifications. |\n| `EMAIL` | Gmail address used for notifications. |\n| `EMAIL_PASSWORD` | Gmail app password. |\n| `DISCORD_WEBHOOK` | Discord webhook URL. |\n| `TELEGRAM_TOKEN` | Telegram bot token. |\n| `TELEGRAM_USER_ID` | Telegram user ID for direct notifications. |\n| `TELEGRAM_LOGS_ENABLED` | Enables Telegram group log forwarding. |\n| `TELEGRAM_LOG_GROUP_ID` | Telegram forum group ID, normally beginning with `-100`. |\n| `TELEGRAM_LOG_INTERVAL_SECS` | Interval used to batch launch logs before sending them. |\n| `TELEGRAM_LOG_TOPIC_LAUNCH_INSTANCE` | Topic ID for launch and retry logs. |\n| `TELEGRAM_LOG_TOPIC_ERRORS` | Topic ID for configuration and unhandled errors. |\n\n## 🩺 Troubleshooting\n\n### 🚫 `Permission denied` when running a script\n\n```bash\nchmod +x setup_env.sh setup_init.sh\n```\n\n### ⏳ First run appears stuck\n\nDependency installation can be quiet for several minutes. Check the active processes from another SSH session:\n\n```bash\nps -ef | grep -E \"setup_init|python3|pip|apt|dpkg\" | grep -v grep\n```\n\n### 🔑 OCI configuration error\n\nInspect:\n\n```bash\ncat ERROR_IN_CONFIG.log\n```\n\nCompare `oci_config` with `sample_oci_config` and verify the absolute `key_file` path.\n\n### ⚠️ Unexpected runtime error\n\nInspect:\n\n```bash\ncat UNHANDLED_ERROR.log\n```\n\nThen restart without reinstalling dependencies:\n\n```bash\n./setup_init.sh rerun\n```\n\n## 📝 Notes\n\n- Existing logs are removed when `setup_init.sh` starts.\n- ARM instances are requested with 2 OCPU and 12 GB RAM.\n- Assigning a public IP is controlled by `ASSIGN_PUBLIC_IP`.\n- Capacity availability is controlled by Oracle; retries do not guarantee immediate creation.\n\n## 🔗 References\n\n- [Oracle OCI Free Tier documentation](https://docs.oracle.com/en-us/iaas/Content/FreeTier/freetier.htm)\n- [Oracle Cloud Free Tier](https://www.oracle.com/cloud/free/)\n- [Oracle Launch Instance API](https://docs.oracle.com/en-us/iaas/api/#/en/iaas/20160918/Instance/LaunchInstance)\n- [Oracle LaunchInstanceDetails](https://docs.oracle.com/en-us/iaas/api/#/en/iaas/20160918/datatypes/LaunchInstanceDetails)\n- [Original capacity automation article](https://hitrov.medium.com/resolving-oracle-cloud-out-of-capacity-issue-and-getting-free-vps-with-4-arm-cores-24gb-of-a3d7e6a027a8)\n\n## 🙏 Credits\n\nOriginally created by [mohankumarpaluru/oracle-freetier-instance-creation](https://github.com/mohankumarpaluru/oracle-freetier-instance-creation).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzxcvresque%2Foracle-freetier-instance-creation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzxcvresque%2Foracle-freetier-instance-creation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzxcvresque%2Foracle-freetier-instance-creation/lists"}