Merge pull request #1228 from drifter089/devContainers

Dev containers

.devcontainer/devcontainer.json

@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText:  PyPSA-Earth and PyPSA-Eur Authors
+//
+// SPDX-License-Identifier: CC-BY-4.0
+// For format details, see https://aka.ms/devcontainer.json.
+{
+  "name": "pypsa earth dev",
+  "image": "ghcr.io/drifter089/pypsa-earth:latest",
+  "workspaceMount": "source=${localWorkspaceFolder},target=/workspaces,type=bind,consistency=cached",
+  "initializeCommand": "docker pull ghcr.io/drifter089/pypsa-earth:latest",
+  "workspaceFolder": "/workspaces",
+  "postAttachCommand": "bash .devcontainer/setup.sh"
+}

.devcontainer/setup.sh

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText:  PyPSA-Earth and PyPSA-Eur Authors
+#
+# SPDX-License-Identifier: CC-BY-4.0
+#!/bin/sh
+
+cat .devcontainer/welcome-message.txt

.devcontainer/welcome-message.txt

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText:  PyPSA-Earth and PyPSA-Eur Authors
+#
+# SPDX-License-Identifier: CC-BY-4.0
+
+
+
+👋 Welcome to the PyPSA-Earth Development Environment!
+
+We’re excited to have you here! This setup allows you to use and contribute to PyPSA-Earth using a development container in VS Code.
+
+📖 Getting Started for New Users
+
+	•	For a step-by-step guide on setting up your environment, debugging, and making your first contribution, refer to the PyPSA-Earth README here: (https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/README.md). It covers everything you need to know as a newcomer.
+	•	The configuration files for the development container are located in the .github/.devcontainer folder.
+
+💡 Tips for New Users
+
+	•	Make the most of VS Code by using the Command Palette (Cmd/Ctrl + Shift + P or F1) for quick access to features and commands.
+	•	If you’re new to development containers, learn the basics at containers.dev.
+
+🚀 Start Exploring and Happy Coding!
+
+Don’t hesitate to reach out if you need help—our community is here to support you. You can access our discord server here: https://discord.gg/AnuJBk23FU

.github/.devcontainer/devcontainer.json

@@ -0,0 +1,33 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/ubuntu
+{
+  "name": "pypsa earth dev",
+  "build": {
+    "dockerfile": "../../Dockerfile"
+  },
+
+  "features": {
+    "ghcr.io/devcontainers-contrib/features/bash-command:1": {},
+    "ghcr.io/eliises/devcontainer-features/bash-profile:1": {}
+  },
+  "customizations": {
+    "vscode": {
+      "terminal.integrated.profiles.linux": {
+        "bash": {
+          "path": "/bin/bash"
+        }
+      },
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "ms-azuretools.vscode-docker",
+        "ms-toolsai.jupyter",
+        "zainchen.json",
+        "tomoki1207.pdf",
+        "grapecity.gc-excelviewer"
+      ]
+    }
+  },
+
+  "postCreateCommand": "python -m pip install --upgrade debugpy"
+}

.github/workflows/devcontainer.yml

@@ -0,0 +1,32 @@
+name: Dev Container Build and Push Image
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+    - envs/linux-pinned.yaml
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      id: checkout
+      uses: actions/checkout@v1
+
+    - name: Login to GitHub Container Registry
+      uses: docker/login-action@v2
+      with:
+        registry: ghcr.io
+        username: ${{ secrets.REGISTRY_USER }}
+        password: ${{ secrets.REGISTRY_TOKEN }}
+
+    - name: Build Dev Container Image
+      uses: devcontainers/ci@v0.3
+      with:
+        subFolder: .github
+        cacheFrom: ghcr.io/${{ github.repository }}-dev-env
+        imageName: ghcr.io/${{ github.repository }}-dev-env
+        push: always

Docker.MD

@@ -0,0 +1,58 @@
+<!--
+SPDX-FileCopyrightText:  PyPSA-Earth and PyPSA-Eur Authors
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+# PyPSA-Earth Development Environment Setup with Docker
+
+This guide provides an alternative way to set up a development environment for **PyPSA-Earth** using Docker containers. This method is particularly useful for users who are not familiar with programming or Python, or who prefer not to install Python directly on their local machine. Using Docker simplifies setup by creating a self-contained environment for PyPSA-Earth.
+
+## Prerequisites
+
+### 1. Install Docker
+
+Ensure Docker is installed on your system. Follow the instructions for your operating system:
+
+- **Windows**: [Docker for Windows](https://docs.docker.com/desktop/install/windows-install/)
+- **Linux**: [Docker for Linux](https://docs.docker.com/desktop/install/linux/)
+- **MacOS**: [Docker for MacOS](https://docs.docker.com/desktop/install/mac-install/)
+
+### 2. Install Visual Studio Code(VSC)
+
+You can use the link [here](https://code.visualstudio.com/download) to install Visual Studio Code on your operating system. Ensure to select the most compatible file for your operating system.
+
+### 3. Install GitHub Desktop
+
+You will also need GitHub Desktop to clone the PyPSA-Earth repository. Install GitHub Desktop for your operating system from [here](https://desktop.github.com/download/).
+
+## Steps to Set Up PyPSA-Earth with Docker
+
+### Step 1: Clone the Repository
+
+1. Open **GitHub Desktop**.
+2. Go to **File** > **Clone Repository**.
+3. Paste the following URL in the URL field:
+
+    ```bash
+    https://github.com/pypsa-meets-earth/pypsa-earth.git
+    ```
+
+4. Click on **Clone**.
+5. Choose the location where you want to save the repository on your local machine.
+6. After cloning, click on **Current Branch: main** and select `devContainers`.
+7. Click on **Open in Visual Studio Code**.
+
+### Step 2: Rebuild and Open in Container
+
+1. Open the cloned repository in **VSCode**.
+2. Click on the icon located at the bottom left corner of the VSCode window.
+3. Select **Reopen in Container**.
+4. Wait for the container to build and for the repository to open in the container.
+
+Once these steps are completed, your development environment will be ready, and you can start using **PyPSA-Earth** in the Docker container.
+
+---
+
+You are now all set up! You can use the development environment to explore PyPSA-Earth and make modifications as needed within the Docker container.
+
+You can start running the tutorial [here](https://pypsa-earth.readthedocs.io/en/latest/short_tutorial.html)

Dockerfile

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText:  PyPSA-Earth and PyPSA-Eur Authors
+#
+# SPDX-License-Identifier: CC-BY-4.0
+FROM condaforge/mambaforge
+
+RUN conda update -n base conda
+RUN conda install -n base conda-libmamba-solver
+RUN conda config --set solver libmamba
+
+RUN apt-get update && apt-get install -y bash git && apt-get install gcc -y
+
+WORKDIR /pypsa-earth
+
+COPY ./envs ./temp
+
+RUN conda env create -n pypsa-earth -f temp/linux-pinned.yaml
+
+RUN conda init bash
+
+RUN touch ~/.bashrc && echo "conda activate pypsa-earth" >> ~/.bashrc
+
+SHELL ["/bin/bash", "--login", "-c"]
+
+ENV PATH /opt/conda/envs/pypsa-earth/bin:$PATH
+
+RUN conda install conda-forge::openjdk -y
+
+RUN rm -r temp
+
+RUN conda clean -afy && \
+    rm -rf /tmp/*
+
+CMD ["bash"]

doc/docker_containers.rst

@@ -0,0 +1,51 @@
+.. SPDX-FileCopyrightText:  PyPSA-Earth and PyPSA-Eur Authors
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. _docker_containers:
+
+Alternate Installation with Docker
+===============================================
+
+This is an alternative way to create a development environment for PyPSA-Earth. This method is useful for users who are not familiar with programming or Python, or who do not want to install Python on their local machine. It uses Docker containers to create a development environment for PyPSA-Earth.
+
+This section provides a step-by-step guide on how to set up and use Docker containers to run PyPSA-Earth.
+
+Steps:
+
+1. Install Docker: Follow the instructions for your operating system:
+
+* `Windows <https://docs.docker.com/desktop/install/windows-install/>`_
+* `Linux <https://docs.docker.com/desktop/install/linux/>`_
+* `MacOS <https://docs.docker.com/desktop/install/mac-install/>`_
+
+    Ensure Docker is installed on your system.
+
+2. You can use the link `here <https://code.visualstudio.com/download>`_ to install Visual Studio Code on your operating system. Ensure to select the most compatible file for your operating system.
+
+3. Install GitHub Desktop for your OS `here <https://desktop.github.com/download/>`_.
+
+4. Clone the repository:
+    * Open GitHub Desktop.
+    * Click on "File" in the top left corner.
+    * Click on "Clone Repository".
+    * Paste the following URL in the URL field:
+
+    .. code:: bash
+
+        https://github.com/pypsa-meets-earth/pypsa-earth.git
+
+    * Click on "Clone".
+    * Choose the location where you want to save the repository.
+    * Click on "Current Branch: main" and select `devContainers`.
+    * Click on "Open in Visual Studio Code".
+
+    The repository will be cloned to your local machine.
+
+5. Rebuild and open in a container:
+    * Open the repository in VSCode.
+    * Click on the icon in the far bottom left corner of the VSCode window.
+    * Click on "Reopen in Container".
+    * Wait for the container to build and open the repository in the container.
+
+    The environment will be ready for use. You can now run PyPSA-Earth in the container.

doc/index.rst

@@ -120,6 +120,7 @@ Documentation
 
 * :doc:`introduction`
 * :doc:`installation`
+* :doc:`docker_containers`
 * :doc:`short_tutorial`
 * :doc:`tutorial`
 * :doc:`data_workflow`
@@ -132,6 +133,7 @@ Documentation
 
    introduction
    installation
+   docker_containers
    short_tutorial
    tutorial
    data_workflow

doc/release_notes.rst

@@ -15,6 +15,7 @@ This part of documentation collects descriptive release notes to capture the mai
 
 * Include option in the config to allow for custom airport data `PR #1241 <https://github.com/pypsa-meets-earth/pypsa-earth/pull/1241>`__
 
+* Added Dev Containers and docker as an option to get started with pypsa-earth `PR #1228 <https://github.com/pypsa-meets-earth/pypsa-earth/pull/1228>`__
 
 **Minor Changes and bug-fixing**