README-1ST.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "d670f2f8-4404-4dad-8f0a-7e64af5312ce",
   "metadata": {},
   "source": [
    "# Lucyfer post installation cheat sheet\n",
    "\n",
    "## Terminal\n",
    "\n",
    "Lucyfer maps `$HOME` to a path in the host running the container, for persistency.  This happens after the `jovyan` account is created, so `/home/jovyan` appears to be empty on first run.  You need to finish configuring the terminal from this notebook.\n",
    "\n",
    "### Missing start up config:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f42fd33f-c58b-44d0-9b08-484210e00f9c",
   "metadata": {},
   "outputs": [],
   "source": [
    "!ls -Al /etc/skel"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bb2782c2-6a08-45ea-847f-d7d7ceee49ee",
   "metadata": {},
   "source": [
    "`bash` configuration:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "76c2f8ff-6910-4ac1-9266-d9f062d0b8f9",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "![[ -e \"$HOME/.bash_profile\" ]] || cp -v \"/etc/skel/.bash_profile\" \"$HOME\"\n",
    "\n",
    "![[ -e \"$HOME/.bash_logout\" ]] || cp -v \"/etc/skel/.bash_logout\" \"$HOME\"\n",
    "\n",
    "![[ -e \"$HOME/.bashrc\" ]] || cp -v \"/etc/skel/.bashrc\" \"$HOME\"\n",
    "\n",
    "![[ -e \"$HOME/.profile\" ]] || cp -v \"/etc/skel/.profile\" \"$HOME\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff2cda11-a186-4044-bff4-533e3414a81e",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true
   },
   "source": [
    "### Shell vi vs emacs key bindings\n",
    "\n",
    "The bash configuration in this section sets the keyboard `vim` style, modal keyboard bindings.  If you wish to use `emacs` bindings (e.g. `Ctl-A` to begining of line) change the `.bash_profile` line:\n",
    "\n",
    "```bash\n",
    "set -o vi\n",
    "```\n",
    "to\n",
    "\n",
    "```bash\n",
    "set -o emacs\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8f13362b-60c8-43cb-8b29-86515e445ad9",
   "metadata": {},
   "source": [
    "---\n",
    "## README-SPARQL\n",
    "\n",
    "Run the [README-SPARQL notebook](./README-SPARQL.ipynb) to validate that graph data SPARQL queries and display work as expected.  Some of those queries are very slow because they run against public DBpedia and Wikipedia endpoints.  Neither database is well-optimized for fast responses."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9a2fd8e9-9b91-4eb1-aec7-b6c0c5fd8213",
   "metadata": {},
   "source": [
    "---\n",
    "## pandoc test"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "65374c2b-0c57-46bd-89e1-20cbd82e23a5",
   "metadata": {},
   "source": [
    "**<span style='color: #f00;'>IMPORTANT</span>**\n",
    "\n",
    "This test fails because the Conda/Linux installation of `pandoc` has a conflict.  Bug raised with the Jupyter team.  Uncomment the line and execute once the issue is resolved."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3573029f-0d0c-46b3-a5ba-0de7434d7887",
   "metadata": {},
   "outputs": [],
   "source": [
    "# !jupyter nbconvert --to pdf \"README-TOO.ipynb\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f4fbe230-b44d-49b8-b6c4-5801807503b2",
   "metadata": {
    "tags": []
   },
   "source": [
    "---\n",
    "## Vim\n",
    "\n",
    "Lightweight `.vimrc` configuration for programming:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "24de6da8-a07d-417b-b205-8c86b203f8b7",
   "metadata": {},
   "outputs": [],
   "source": [
    "![[ -e \"$HOME/.vimrc\" ]] || cp -v \"/etc/skel/.vimrc\" \"$HOME\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c43ce20-770d-4f7f-b874-eb9b788719b1",
   "metadata": {},
   "source": [
    "### NERDTree installation\n",
    "\n",
    "Vim 8 packages setup; cleanest and easiest."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "58354ed3-b21e-4d10-aa72-60dc5e74b5b8",
   "metadata": {},
   "outputs": [],
   "source": [
    "![[ -d \"$HOME/.vim/pack/vendoer/start/nerdtree\" ]] || \\\n",
    "    git clone https://github.com/preservim/nerdtree.git ~/.vim/pack/vendor/start/nerdtree && \\\n",
    "    vim -u NONE -c \"helptags ~/.vim/pack/vendor/start/nerdtree/doc\" -c q"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f135a113-80d8-4114-889c-a14d3d20fa03",
   "metadata": {},
   "source": [
    "Enable the NERDTree in `.vimrc` to always open on starting the editor from the command line:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4ebf381e-9179-4a87-b5c6-ab40a4b62f44",
   "metadata": {},
   "outputs": [],
   "source": [
    "!awk '/NERDTree/ { b = 1; } END { exit(!b); }' \"$HOME/.vimrc\" || \\\n",
    "    echo 'autocmd VimEnter * NERDTree | set nu' | tee -a \"$HOME/.vimrc\" && \\\n",
    "    echo 'autocmd VimEnter * if len($TERM) && argc() | wincmd l | endif' | tee -a \"$HOME/.vimrc\" && \\\n",
    "    echo \"NERDTree on start installed\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "997a127d-16c7-4276-98d2-c08d50bac9a7",
   "metadata": {},
   "source": [
    "---\n",
    "## .gitignore\n",
    "\n",
    "There's a sample `.gitignore` file available in `/etc/skel` that you may use as a basis.  It ignores Lucyfer, PTPython, iPython, build, and PyCharm temporary files."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cae18d7f-14e5-4926-a35d-c47957b53e7a",
   "metadata": {},
   "source": [
    "---\n",
    "## GPG keys for GitHub code signing\n",
    "\n",
    "Some projects require committers to sign their commits using a PGP/GPG key added to their GitHub or GitLab accounts  This section explains how to get the keys to work in Lucyfer **and** in the hosting machine, to avoid duplicating keys or configurations.\n",
    "\n",
    "First ensure that you have a valid key:\n",
    "\n",
    "- Creating a GPG key pair (if you don't already have one):\n",
    "- Extract and import existing key to a new machine:\n",
    "\n",
    "The new machine, in this case, is the Lucyfer image.  **<span style='color: #ffa500'>Although you may create a key from a Lucyfer console, it's not recommended.</span>**  Create the key pair outside of Lucyfer and import it into this environment.\n",
    "\n",
    "### Example\n",
    "\n",
    "User name `alice` uses her current machine for experimentation and development in the `$HOME/development/widget` directory.  Lucyfer and PyCharm both point at the `widget` directory for source files, tests, and notebooks.  `alice` runs these commands to export her private keys to the Lucyfer environment:\n",
    "\n",
    "```bash\n",
    "\n",
    "gpg --list-secret-keys alice@example.com\n",
    "\n",
    "# Finds the key, which is the long hexadecimal number next to, or above her email address\n",
    "# depending on the GPG version installed.  For this example, let's call it: 4269B0B0A9\n",
    "\n",
    "gpg --export-secret-keys \"4269B0B0A9\" > ~/development/widget/private.key\n",
    "```\n",
    "\n",
    "GPG will ask for the user's passphrase, then output the binary representation of the key to `~/development/widget/private.key`.  The key is ready for import into Lucyfer."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "27b048a9-1d40-4fde-9955-f19407e36270",
   "metadata": {},
   "source": [
    "### Importing the key to Lucyfer\n",
    "\n",
    "1. Open a terminal console\n",
    "2. Copy the private key from earlier in this section to the Lucyfer working directory as `private.key`\n",
    "3. Execute this code in the terminal console:\n",
    "\n",
    "   ```bash\n",
    "   gpg --import \"./private.key\" && rm -f \"./private.key\"\n",
    "   ```\n",
    "\n",
    "4. Enter the passphrase\n",
    "\n",
    "Done!  You can check it's in by running:\n",
    "\n",
    "```bash\n",
    "!gpg --list-keys alice@example.com\n",
    "```\n",
    "\n",
    "Don't forget to use the email address associated with your email address."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "006b4962-02ab-40ba-a29c-057cad3bff42",
   "metadata": {},
   "source": [
    "### Adding a GPG key to your GitHub account\n",
    "\n",
    "By adding the key into Lucyfer, you will be able to run Git commands and commits from within this environment, from the native IDE, from the native console, or from your favorite Git client (e.g. SourceTree).\n",
    "\n",
    "Follow these <a href='https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account' target='_new'>instructions on how to add your GPG key to your GitHub account</a>."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}