Added steps to run oracle database 23c free on Mac M1 chip in FAQ.md (#…

…2643)

OracleDatabase/SingleInstance/FAQ.md

@@ -4,11 +4,13 @@
 
 Yes, this feature is supported version 19.3 onwards.
 
-Versions prior to 19.3 available on the [Oracle Container Registry](https://container-registry.oracle.com/), like the Oracle Database 12c Standard Edition 2 and Enterprise Edition images, are not based on any of the Dockerfiles contained in this repository. For such versions, if you require the runtime functionality documented in this repository, you will need to build an image from the appropriate Dockerfile.
+Versions prior to 19.3 available on the [Oracle Container Registry](https://container-registry.oracle.com/), like the Oracle Database 12c Standard Edition 2 and Enterprise Edition images, are not based on any of the Dockerfiles contained in this repository.
+For such versions, if you require the runtime functionality documented in this repository, you will need to build an image from the appropriate Dockerfile.
 
 ## How do I change the timezone of my container
 
-As of Docker 17.06-ce, Docker does not yet provide a way to pass down the `TZ` Unix environment variable from the host to the container. Because of that all containers run in the UTC timezone. If you would like to have your database run in a different timezone you can pass on the `TZ` environment variable within the `docker run` command via the `-e` option. An example would be: `docker run ... -e TZ="Europe/Vienna" oracle/database:12.2.0.1-ee`. Another option would be to specify two read-only volume mounts: `docker run ... -v /etc/timezone:/etc/timezone:ro -v /etc/localtime:/etc/localtime:ro oracle/database:12.2.0.1-ee`. This will synchronize the timezone of the the container with that of the Docker host.
+As of Docker 17.06-ce, Docker does not yet provide a way to pass down the `TZ` Unix environment variable from the host to the container. Because of that all containers run in the UTC timezone. If you would like to have your database run in a different timezone you can pass on the `TZ` environment variable within the `docker run` command via the `-e` option.
+An example would be: `docker run ... -e TZ="Europe/Vienna" oracle/database:12.2.0.1-ee`. Another option would be to specify two read-only volume mounts: `docker run ... -v /etc/timezone:/etc/timezone:ro -v /etc/localtime:/etc/localtime:ro oracle/database:12.2.0.1-ee`. This will synchronize the timezone of the the container with that of the Docker host.
 
 ## Can I run Oracle Database containers on Apple M1 (Arm) devices?
 
@@ -25,7 +27,8 @@ which are not available for that architecture.
 
 This error is thrown when there is no sufficient space available within the container to unzip the install binaries and run the installation of the Oracle database. The container runs the `df` Unix command, meaning that even if you think there should be enough space, there certainly isn't within the container.
 
-Please make sure that you have enough space available. If you use a storage diver such as `overlay2`, make sure that the output of `docker info` shows a `Base Device Size:` that is bigger than the required space. If not, please change the Base Device Size via the `--storage-opt dm.basesize=` option for the Docker daemon, see [this thread on Docker forums](https://forums.docker.com/t/increase-container-volume-disk-size/1652/4) for more information on that. **Note: You will have to delete all images afterwards to make sure that the new setting is picked up!**
+Please make sure that you have enough space available. If you use a storage diver such as `overlay2`, make sure that the output of `docker info` shows a `Base Device Size:` that is bigger than the required space.
+If not, please change the Base Device Size via the `--storage-opt dm.basesize=` option for the Docker daemon, see [this thread on Docker forums](https://forums.docker.com/t/increase-container-volume-disk-size/1652/4) for more information on that. **Note: You will have to delete all images afterwards to make sure that the new setting is picked up!**
 
 ## Error: The container doesn't have enough memory allocated. A database XE container needs at least 1 GB of shared memory (/dev/shm)
 
@@ -37,7 +40,8 @@ CRC errors by the Unix unzip command during image build can be caused by a lack
 
 ## "Cannot create directory" error when using volumes
 
-This is a Unix file system permission issue. Docker by default will map the `uid` inside the container to the outside world. The `uid` for the `oracle` user inside the container is `54321` and therefore all files are created with this `uid`. If you happen to have your volume pointed at a location outside there container where this `uid` doesn't have any permissions for, the container can't write to it and therefore the database files creation fails. There are several remedies for this situation:
+This is a Unix file system permission issue. Docker by default will map the `uid` inside the container to the outside world. The `uid` for the `oracle` user inside the container is `54321` and therefore all files are created with this `uid`.
+If you happen to have your volume pointed at a location outside there container where this `uid` doesn't have any permissions for, the container can't write to it and therefore the database files creation fails. There are several remedies for this situation:
 
 * Use named volumes
 * Change the ownership of your folder to `54321`
@@ -110,3 +114,83 @@ Refer to the [module documentation](https://python-oracledb.readthedocs.io/en/la
 ## ORA-01157: cannot identify/lock data file
 
 This error occurs when the database cannot find a data file (used for tablespaces) that was previously present. This is most likely because the data file has been located outside the volume in a previous container and was hence not persisted. Ensure that when you add tablespaces and/or data files that they are located within the volume location, i.e. $ORACLE_BASE/oradata/$ORACLE_SID, (e.g. `/opt/oracle/oradata/XE`).
+
+## Running Oracle Database 23c Free on Apple Silicon (ARM) chip
+
+### Setup Database
+Below are the steps to run Oracle Database 23c Free on Apple Silicon (ARM) machine
+
+1. Install [Podman Lima](https://github.com/lima-vm/lima) on Mac
+
+    ```brew install podman lima```
+
+2. Start a lima instance (vm)
+
+    ```limactl start --name podman-amd64  --set='.arch = "x86_64" | .memory = "10GiB"'  template://podman```
+
+    Wait for the VM to boot up. Above command may error out if the VM takes a while to boot up. Ultimately it comes up fine.
+
+3. Set the address or hostname of the lima container runtime
+
+    ```export CONTAINER_HOST=unix://Users/$USER/.lima/podman-amd64/sock/podman.sock```
+
+4. Pull the oracle database 23c free image
+
+    ```podman pull container-registry.oracle.com/database/free:latest```
+
+5. Run the container with the pulled image
+
+    ```podman run -e ORACLE_PWD=<password> -d -P container-registry.oracle.com/database/free:latest```
+
+6. Check whether the database came up healthy.
+
+```shell
+    $ podman ps -a
+        CONTAINER ID  IMAGE                                               COMMAND               CREATED        STATUS                  PORTS                    NAMES 
+        825dcbd3e822  container-registry.oracle.com/database/free:latest  /bin/sh -c exec $...  4 minutes ago  Up 4 minutes (healthy)  0.0.0.0:42439->1521/tcp  hopeful_yalow
+```
+
+### Connect
+1. Install sqlplus
+
+   ```cd $HOME/Downloads```
+
+   ```curl -O https://download.oracle.com/otn_software/mac/instantclient/198000/instantclient-basic-macos.x64-19.8.0.0.0dbru.dmg```
+
+   ```curl -O https://download.oracle.com/otn_software/mac/instantclient/198000/instantclient-sqlplus-macos.x64-19.8.0.0.0dbru.dmg```
+
+   ```hdiutil mount instantclient-basic-macos.x64-19.8.0.0.0dbru.dmg```
+
+   ```hdiutil mount instantclient-sqlplus-macos.x64-19.8.0.0.0dbru.dmg```
+
+   ```/Volumes/instantclient-basic-macos.x64-19.8.0.0.0dbru/install_ic.sh```
+
+   ```hdiutil unmount /Volumes/instantclient-basic-macos.x64-19.8.0.0.0dbru```
+
+   ```hdiutil unmount /Volumes/instantclient-sqlplus-macos.x64-19.8.0.0.0dbru```
+
+2. Test the connection:
+
+   ```$HOME/Downloads/instantclient_19_8/sqlplus sys@localhost:<PORT>/FREE as sysdba```
+
+   ```$HOME/Downloads/instantclient_19_8/sqlplus system@localhost:<PORT>/FREE```
+
+   ```$HOME/Downloads/instantclient_19_8/sqlplus pdbadmin@localhost:<PORT>/FREEPDB1```
+
+    PORT is 42439 in above e.g. (Step 6 output of "podman ps -a").
+
+Alternative (Using SQLcl):
+
+1. Install [Java](https://download.oracle.com/java/20/latest/jdk-20_macos-aarch64_bin.dmg)
+
+2. Install [SQLcl](https://download.oracle.com/otn_software/java/sqldeveloper/sqlcl-latest.zip)
+
+3. Test the connection:
+
+   ```sqlcl/bin/sql sys@localhost:<PORT>/FREE as sysdba```
+
+   ```sqlcl/bin/sql system@localhost:<PORT>/FREE```
+
+   ```sqlcl/bin/sql pdbadmin@localhost:<PORT>/FREEPDB1```
+
+   PORT is 42439 in above e.g. (Step 6 output of "podman ps -a").