{"id":20819525,"url":"https://github.com/pyroscope/alma-nap","last_synced_at":"2025-08-20T07:23:17.318Z","repository":{"id":46815324,"uuid":"62400494","full_name":"pyroscope/alma-nap","owner":"pyroscope","description":"Ansible-powered setup of a Linux web host with MySQL and ACME-enabled Nginx running applications written in Python and/or PHP","archived":false,"fork":false,"pushed_at":"2023-01-24T23:15:13.000Z","size":67,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-31T11:21:29.638Z","etag":null,"topics":["acme","ansible","ansible-playbooks","debian","linux","mysql","nginx","php","python","ubuntu"],"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/pyroscope.png","metadata":{"files":{"readme":"README.rst","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}},"created_at":"2016-07-01T14:56:44.000Z","updated_at":"2021-08-27T07:58:16.000Z","dependencies_parsed_at":"2023-02-14T02:30:30.045Z","dependency_job_id":null,"html_url":"https://github.com/pyroscope/alma-nap","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyroscope%2Falma-nap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyroscope%2Falma-nap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyroscope%2Falma-nap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyroscope%2Falma-nap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyroscope","download_url":"https://codeload.github.com/pyroscope/alma-nap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252903075,"owners_count":21822367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["acme","ansible","ansible-playbooks","debian","linux","mysql","nginx","php","python","ubuntu"],"created_at":"2024-11-17T22:06:40.441Z","updated_at":"2025-05-07T15:23:05.665Z","avatar_url":"https://github.com/pyroscope.png","language":"Python","readme":"ALMA-NAP Web Engine\n===================\n\n*Ansible-powered setup of a Linux web host with MySQL and ACME-enabled Nginx running applications written in Python and/or PHP.*\n\n.. contents:: **Contents**\n\n\nWhat is It?\n-----------\n\n*ALMA-NAP* uses *Ansible* to set up a working *Linux*-based webserver environment\ncomprised of *MySQL*, an *ACME*-enabled *Nginx* (i.e. having “Let's Encrypt” certificates),\nand applications written in *Python* and/or *PHP*. “Alma nap” also means “apple day”\nin Hungarian, whatever you make of that —\nmaybe ‘an apple (a) day keeps the self-signed certificate away’. :grinning:\n\nBy default, a HTTPS-only setup is created, with HTTP supported only for\nthe necessary ACME callbacks used during certificate signing.\n``ufw`` is installed and used to manage port 80 dynamically during the\ncertificate signing and renewal process, unless port 80 was open to start with.\n\nAdditionally, some related tools can be installed:\n\n* *GitLab CE* to manage your web site source code, including the *Mattermost* group chat server that comes with it.\n* If you prefer a more traditional team chat, `Unreal IRCd`_ with `Anope`_ services.\n\n*ALMA-NAP* is MIT-licensed.\n\nIf you have questions or need help, please use the `pyroscope-users`_ mailing list\nor the inofficial ``##rtorrent`` channel on ``irc.freenode.net``.\n\n**WARNING:** This project is not feature-complete yet, consider it beta.\nThe parts that are committed are tested and do work,\nbut expect changes regarding the structure of the configuration values and such.\n\n\nHow Do I Use It?\n----------------\n\nThe Big Picture\n^^^^^^^^^^^^^^^\n\n*Ansible* works by remotely controlling a *target host* to provision\nsoftware and its configuration automatically.\nIf you're new to *Ansible*, it's highly recommended to watch their `Quickstart Video`_\nand read the `Getting Started`_ guide *now*.\n\nAt the moment, this project only supports Debian-like Linux distributions as the target.\nSpecifically, the stable 64bit server releases of *Debian* (Jessie) or *Ubuntu* (Xenial)\nare recommended; their previous versions should also work (*Wheezy* and *Trusty*).\nYou also need a Linux, BSD, Mac OSX, or other POSIX system as the controlling computer.\nOn Windows, start a VM with the latest Ubuntu LTS (Xenial).\n\nBefore you begin, consider reading this whole README to the end, so that you know what's\nahead of you, and also know about customization options you might want to apply.\n\n\nPreparing Your Workstation\n^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nFirst, check out this repository and call the working environment bootstrapper:\n\n.. code-block:: shell\n\n    git clone https://github.com/pyroscope/alma-nap.git\n    cd alma-nap\n    ./bootstrap.sh\n    . .env\n\nIt creates a Python virtualenv and installs some Python tools into it.\nThis includes *Ansible v1.9.6*, so you don't have to worry about\nhaving the correct version installed on your workstation.\n\nNext, define a moniker for the *target host* in the ``~/.ssh/config`` file\n— create one if it doesn't exist yet.\nYou need to change ``Host`` and ``HostName`` to fitting values.\n\n.. code-block:: ini\n\n    Host example-host\n        HostName www.example.com\n        User deploy\n        IdentityFile ~/.ssh/deploy\n        IdentitiesOnly yes\n\nIt is recommended you use the ``deploy`` user and its key as shown,\nas the rest of the documentation works with that user account.\nWe'll create a SSH key for it later on.\nAlso, everytime you see the value ``example-host`` below,\nreplace it with your own ``Host`` value.\n\nAlso create a custom *Ansible* inventory file similar to the ``hosts`` example\n— call it ``myhosts`` and add the following:\n\n.. code-block:: ini\n\n    # Ansible Host Inventory\n\n    [www]\n    example-host\n\n    [gitlab]\n    # example-host\n\nIf you want `Gitlab CE`_ installed, uncomment the second entry.\n\n\nPreparing Your Target Host\n^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nIn a dedicated terminal window, open a ``root`` shell to your target host.\nKeep this open **ALL THE TIME** since the ``security`` role hardens your SSH server,\nand depending on your exact setup and login procedure you could lock yourself out.\nThat SSH window is your life-line to fix things, especially if you have no\nphysical access to the target host.\n\nCommands that should be entered into that terminal are marked with ``root@example-host#`` further below,\nwhile ``you@workstation$`` indicates commands that should be run in the project working directory.\n\n**IMPORTANT:** While most configuration goes to dedicated user accounts,\nsome global files are affected that you might have customized beforehand.\nSo if the target host is not a brand-new machine with a pristine OS install,\n**make a backup of your /etc and webserver directories** before you continue, for example using\n``( cd / \u0026\u0026 tar cvfz /root/etc+www-bak-$(date +'%Y-%m-%d-%H%M').tgz etc var/www )``.\n\nThe ``accounts`` role will add the configured admin accounts on the first *Ansible* run,\nby default a user named ``deploy``.\nNote that you need to provide the public key of that user,\nto create a new one use this command:\n\n.. code-block:: shell\n\n    you@workstation$\n    ssh-keygen -b 4096 -t rsa -C \"Ansible Deployment\" -f ~/.ssh/deploy\n\nSome minimal configuration regarding the target host is also needed, so\nadd a file named ``host_vars/«example-host»/main.yml`` to the project directory.\n\n.. code-block:: yaml\n\n    ---\n    ansible_sudo: true\n\n    motd_description: \"SHORT SERVER DESCRIPTION HERE\"\n    nginx_server_name: \"{{ ansible_fqdn }}\"\n\nAn example file is in ``host_vars/alma-nap-dev/main.yml``.\n\nPerform your first ``ansible-playbook`` run with a combination of\n``--user=REMOTE_USER``, ``--ask-pass``,\n``--become``, ``--become-user=BECOME_USER``, ``--ask-become-pass``,\nand ``--become-method=BECOME_METHOD``.\nNot all of these are needed, use a sensible combination,\ne.g. ``--user=root --ask-pass`` for an initial ``root`` login with a password,\nwhich is a common way that credentials for a new cloud server are handed to you.\n\nThe next call does the mentioned initial setup, installing some basic packages\nand creating admin accounts. Change the ``--user`` and ``--ask-pass`` options\nif needed, as explained in the paragraph above.\n\n.. code-block:: shell\n\n    you@workstation$\n    ansible-playbook -i myhosts site.yml -l example-host -t base,acc --user=root --ask-pass\n\nNow, set a ``sudo`` password for the new admin account (in your ``root`` shell):\n\n.. code-block:: shell\n\n    root@example-host#\n    passwd deploy\n\nThen insert this password into a new file named ``host_vars/«example-host»/secrets.yml``\nwith the following content:\n\n.. code-block:: yaml\n\n    ---\n    ansible_sudo_pass: YOUR_DEPLOY_ACCOUNT_PASSWORD_HERE\n\n\nYou're ready to test the connection now, use the ``ansible`` command as shown:\n\n.. code-block:: shell\n\n    you@workstation$ ansible www -i myhosts -m setup -a \"filter=*distribution*\"\n    example-host | success \u003e\u003e {\n        \"ansible_facts\": {\n            \"ansible_distribution\": \"Debian\",\n            \"ansible_distribution_major_version\": \"8\",\n            \"ansible_distribution_release\": \"jessie\",\n            \"ansible_distribution_version\": \"8.5\"\n        },\n        \"changed\": false\n    }\n\nIf you do not get a success message like the above, use the power of the Internet,\ne.g. by reading the `Troubleshooting SSH connections in Ansible`_ blog post,\nor checking out the official *Ansible* documentation.\n\n\n“Let's Encrypt” Registration\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n\nInitial Full Run\n^^^^^^^^^^^^^^^^\n\nIt is time to install the rest of the software stack:\n\n.. code-block:: shell\n\n    you@workstation$\n    ansible-playbook -i myhosts site.yml -l example-host\n\n\n\n\n\nCompleting Your Setup\n^^^^^^^^^^^^^^^^^^^^^\n\n**Secure the GitLab ``root`` Account**\n\nNote that *GitLab* is only installed when you add a host to the ``[gitlab]`` group in the inventory.\n\nOpen the *GitLab* web interface and change the admistrator password to something secure and unique.\nIt's recommended that you also create an additional administrator account ``«you»-admin``\nin addition to the one you use normally.\nUse ``root`` only in case of emergencies.\n\n\n**Disable Root and Password Login**\n\nSo that people *not* reading this documentation don't lock themselves\nout of their servers, the two critical values regarding this\nhave *unsecure* but *safe* defaults.\nTo rememedy that, add the following to the ``group_vars/all/main.yml`` file:\n\n.. code-block:: yaml\n\n    ---\n    sshd_PasswordAuthentication: false\n    sshd_PermitRootLogin: false\n\nThen re-run the playbook as follows:\n\n.. code-block:: shell\n\n    you@workstation$\n    ansible-playbook -i myhosts site.yml -l example-host -t sec\n\nNow test in a new terminal that you can still access the server by\nlogging in to the ``deploy`` account, which should always work,\nsince that is a non-root account with pubkey authentication.\nBut better make sure…\n\n\n**Enable the UFW Firewall Rules**\n\nThe `Uncomplicated Firewall`_ (UFW) tool is installed by the ``ufw`` role,\ntogether with firewall rules matching the installed software and its\nconfiguration.\nActivating the firewall is left as a manual task, since you can make\na remote server pretty much unusable when SSH connections get disabled by accident\n— only a rescue mode or virtual console can help to avoid a full reinstall then,\nif you have no physical access to the machine.\n\n.. code-block:: shell\n\n    root@example-host#\n    ufw show added\n    # Make sure the output contains\n    #   ufw limit 22/tcp\n    ufw enable  # activate the firewall\n    ufw status verbose  # show all the settings\n\nIf the firewall status is printed to the console, you made it. :tada:\n\n\nPHP Application Considerations\n------------------------------\n\nThe default configuration comes with multiple PHP hardening settings\nthat might break some features of your application.\nPlease check the following points and if there is a conflict,\neither improve your code or adapt the default values.\n\n* Make sure you're not relying on side effects of assertions.\n* If your application writes to disk outside of ``/tmp`` and ``/var/www``, then change ``open_basedir`` accordingly.\n\n\nMore Technical Details\n----------------------\n\n\nCredits\n-------\n\n* The ``gitlab`` role is based on `geerlingguy/ansible-role-gitlab`_ (v1.2.1, BSD/MIT).\n* A copy of `diafygi/acme-tiny`_ is used (`fcb7cd6` from 2015-12-29, MIT), with slight modifications.\n\n\n.. _`pyroscope-users`: http://groups.google.com/group/pyroscope-users\n.. _`Quickstart Video`: https://docs.ansible.com/ansible/quickstart.html\n.. _`Getting Started`: https://docs.ansible.com/ansible/intro_getting_started.html\n.. _`Gitlab CE`: https://about.gitlab.com/features/#community\n.. _`Troubleshooting SSH connections in Ansible`: https://sgargan.blogspot.de/2013/10/troubleshooting-ssh-connections-in.html\n.. _`Uncomplicated Firewall`: https://en.wikipedia.org/wiki/Uncomplicated_Firewall\n.. _`Unreal IRCd`: https://www.unrealircd.org/\n.. _`Anope`: https://www.anope.org/\n.. _`geerlingguy/ansible-role-gitlab`: https://github.com/geerlingguy/ansible-role-gitlab\n.. _`diafygi/acme-tiny`: https://github.com/diafygi/acme-tiny\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyroscope%2Falma-nap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyroscope%2Falma-nap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyroscope%2Falma-nap/lists"}