====== EE5311 Digital IC Design Lab Setup (July-Nov 2026) ======

===== Prerequisites =====

==== 1. Docker ====

Install Docker on your machine using the instructions from:

  * macOS: [[https://docs.docker.com/desktop/setup/install/mac-install/|mac-install]]
  * Linux: [[https://docs.docker.com/desktop/setup/install/linux/|linux-install]]
      * Linux users ensure you are able to run docker as non-root user by following the instructions [[https://docs.docker.com/engine/install/linux-postinstall/|here]]. Other steps described below do not work for the root user.
  * Windows: [[https://docs.docker.com/desktop/setup/install/windows-install/|win-install]]

==== 2. VNC client/viewer ====

Download a VNC client/viewer for your platform to interact with the image.

Suggested VNC viewers:

  * Windows: [[https://www.tightvnc.com/download.php|TightVNC]]
  * macOS has a couple of inbuilt VNC viewers: (a) ''Connect to server'' option in Finder (shortcut: ⌘+K)  (b) ''Screen Sharing'' application
  * Most Linux distros come pre-packaged with [[https://remmina.org/|Remmina]]. If you are not a fan, try [[https://tigervnc.org/|TigerVNC]].

===== Downloading the docker image =====

The image can downloaded from two sources:

  - EE VLSI website:
    - Intel/AMD CPU users : {{:courses:ee5311_2026:ee5311_iitm.tar.gz|EE5311 AMD64 docker image}}
    - ARM CPU users : {{:courses:ee5311_2026:ee5311_iitm_arm64.tar.gz|EE5311 ARM64 docker image}} (M1 or later macs and Windows on ARM) 
  - [[https://hub.docker.com/r/srampr/ee5311_iitm|Docker hub]]

Images from both sources are identical. The recommended option, especially within the IITM network, is the first one, given the size of the compressed image (~600MB). Use the second option if you are outside the IITM network or if the first one is inaccessible.

Download the compose script for your platform:
   * Linux and MacOS users:
      - Download {{:courses:ee5311_2026:compose.sh|compose.sh}}.
      - Add executable permissions to ''compose.sh'' using: ''chmod +x compose.sh''.
   * Windows users: Download {{:courses:ee5311_2026:compose.bat|compose.bat}}.
If you chose:
  * the first option (downloading the local image),
    - Install the image using:
      * Intel/AMD : ''docker load -i ee5311_iitm.tar.gz'' 
      * ARM : ''docker load -i ee5311_iitm_arm64.tar.gz''.
    - Ensure that the image is installed using the ''docker images'' command in terminal. It should list an image named ''srampr/ee5311_iitm:jul_nov_2026''.
    - You can optionally delete the ''ee5311_iitm.tar.gz''/''ee5311_iitm_arm64.tar.gz'' file to save space after installing and verifying it.
  * the second option (using Docker Hub), the first time you invoke the ''compose.sh''/''compose.bat'' script, the image will be automatically downloaded from Docker hub.

===== Compose Script Usage =====

The compose script (''compose.sh'' for Linux/macOS and ''compose.bat'' for Windows) takes the following arguments:

^ Switch     ^ Description ^
| ''up''          | Starts a saved container if one exists; otherwise, starts a new one.        |
| ''down''     | Saves the running container and shuts it down.                              |
| ''fresh''     | Forces a new container to start, ignoring any saved container.              |
| ''save''       | Force-saves the running container.                                          |
| ''pause''    | Freezes the running container (will be erased if you restart your machine). |
| ''resume'' | Unfreezes the paused container.                                             |

The only arguments you //typically// need to use are ''up'' to start and ''down'' to terminate your sessions.

  * Linux and macOS users: ''./compose.sh up'' or ''./compose.sh down''.
  * Windows users: ''.\compose.bat up'' or ''.\compose.bat down''.

This will run the container in the background using Docker Compose.

  * The running container **should** start a VNC session in the background in your machine at the port ''localhost:99''.
  * To connect to this session, open the VNC viewer you installed in [[courses:ee5311_2026:lab_setup#vnc_clientviewer|Step 2]] of Prerequisites. Use ''localhost:99'' as the address to connect.

If you are unable to connect to this VNC session in your first attempt, run ''./compose down'', then ''./compose.sh fresh'', and then try connecting to the VNC session.

**WARNING:**\\
''pause'' and ''resume'' will save and restore the session exactly as you left it, including the GUI state. Catch is that ''pause'' and ''resume'' states are erased if you restart your machine. ''save'' does not preserve your GUI state but is persistent across machine restarts. ''save'' and ''up'' together behave like logging out of and logging back into your computer.

===== Password =====

''ee5311'' is the password for both the VNC session and the local user inside the image.

===== Data =====

All schematic, simulation, and layout results are stored in the ''ee5311'' directory in your home directory (both inside the docker container and in your machine). You can change this path in ''compose.sh'' (or ''compose.bat'') if you would like them stored elsewhere.