{"id":19167079,"url":"https://github.com/powerman/narada","last_synced_at":"2025-05-07T13:36:45.054Z","repository":{"id":26894444,"uuid":"30355774","full_name":"powerman/Narada","owner":"powerman","description":"Framework for ease deploy and support microservice projects","archived":false,"fork":false,"pushed_at":"2018-04-04T12:14:12.000Z","size":654,"stargazers_count":7,"open_issues_count":5,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-18T16:43:04.134Z","etag":null,"topics":["backup","configuration","cron","deploy","deployment","framework","lock","logging","microservices","migration","mysql","narada","perl","perl-module","project-templates","qmail","runit"],"latest_commit_sha":null,"homepage":"https://metacpan.org/pod/Narada","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/powerman.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","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":"2015-02-05T13:05:24.000Z","updated_at":"2023-09-28T09:34:38.000Z","dependencies_parsed_at":"2022-09-02T04:00:23.605Z","dependency_job_id":null,"html_url":"https://github.com/powerman/Narada","commit_stats":null,"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/powerman%2FNarada","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/powerman%2FNarada/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/powerman%2FNarada/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/powerman%2FNarada/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/powerman","download_url":"https://codeload.github.com/powerman/Narada/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249822256,"owners_count":21329944,"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":["backup","configuration","cron","deploy","deployment","framework","lock","logging","microservices","migration","mysql","narada","perl","perl-module","project-templates","qmail","runit"],"created_at":"2024-11-09T09:35:43.591Z","updated_at":"2025-04-19T22:34:59.204Z","avatar_url":"https://github.com/powerman.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/powerman/Narada.svg?branch=master)](https://travis-ci.org/powerman/Narada)\n[![Coverage Status](https://coveralls.io/repos/powerman/Narada/badge.svg?branch=master)](https://coveralls.io/r/powerman/Narada?branch=master)\n[![Docker Automated Build](https://img.shields.io/docker/automated/powerman/narada.svg)](https://github.com/powerman/Narada)\n[![Docker Build Status](https://img.shields.io/docker/build/powerman/narada.svg)](https://hub.docker.com/r/powerman/narada/)\n\n# NAME\n\nNarada - framework for ease deploy and support microservice projects\n\n# VERSION\n\nThis document describes Narada version v2.3.8\n\n# SYNOPSIS\n\n    #--- Create new project\n    ~ $ narada-new my_proj\n    ... New project will be created using template (from git repo).\n\n    #--- Develop project as usually, until it's ready to run\n    ~ $ cd my_proj\n    ~/my_proj $\n    ... Now you in project's source dir with git repo.\n    ... You can develop this project in any way and language.\n\n    #--- Make release and deploy it to check how it works\n    ... NOTE: This operation is usually automated by script(s) provided\n    ... by \"project template\" used while creating new project.\n    ... Create file 0.1.0.migrate with instructions how to migrate between\n    ... empty directory and version 0.1.0 of your project plus any related\n    ... 0.1.0.{patch,tgz,etc.} files if you need them.\n    ... Copy these files into .release/ subdirectory of directory where\n    ... you want to deploy this version of project, for ex. in _live/.\n    ~/my_proj $ cp 0.1.0.* _live/.release/\n    ~/my_proj $ cd _live\n    ~/my_proj/_live $ narada-install 0.1.0\n    ... Now you in project's deploy directory, with config files, logs,\n    ... running services, data files, etc. and you can check how it works.\n\n    #--- Upgrade or downgrade project\n    ... Repeat same steps to prepare 0.2.0.migrate and save into .release/.\n    ~/my_proj/_live $ narada-install 0.2.0\n    ... You can downgrade if something goes wrong.\n    ~/my_proj/_live $ narada-install 0.1.0\n\n    #--- You may need to update project's external configuration/data\n    ~/my_proj/_live $ narada-setup-cron\n    ~/my_proj/_live $ narada-setup-mysql\n    ~/my_proj/_live $ narada-setup-qmail\n    ~/my_proj/_live $ narada-start-services\n\n    #--- You may need to backup this version and restore another one\n    ~/my_proj/_live $ narada-backup\n    ~/my_proj/_live $ cp .backup/full.tar .backup/full-0.2.0.tar\n    ~/my_proj/_live $ narada-restore .backup/full-0.1.0.tar\n\n    #--- You may need to lock project while manual maintenance\n    ~/my_proj/_live $ narada-lock-exclusive\n    [LOCKED] ~/my_proj/_live $\n    ... Now all project applications will be blocked on next attempt\n    ... to read/write any file or database, so you can safely change\n    ... project files or databases, etc.\n    [LOCKED] ~/my_proj/_live $ exit\n    ~/my_proj/_live $\n    ... Now project applications will be unblocked and continue to work.\n\n    #--- Manage project\n    ... View/monitor project's log.\n    ~/my_proj/_live $ narada-viewlog\n    ... Get console access to project's database.\n    ~/my_proj/_live $ narada-mysql\n\n    #--- Stop and uninstall this project.\n    ... Cleanup related external configurations.\n    ~/my_proj/_live $ narada-setup-cron --clean\n    ~/my_proj/_live $ narada-setup-mysql --clean\n    ~/my_proj/_live $ narada-setup-qmail --clean\n    ... Kill all related background processes.\n    ~/my_proj/_live $ narada-shutdown-services\n    ~/my_proj/_live $ narada-bg-killall\n    ... Then just remove it.\n    ~/my_proj/_live $ cd ..\n    ~/my_proj $ rm -rf _live/\n\n# DESCRIPTION\n\nNarada was designed for ease development, deploy and support for medium/big\nserver-side project or large amount of small projects (used in microservice\narchitecture). It's a framework which define **the way to manage** your\nproject (which doesn't really depend on your project's nature), and\ndoesn't restrict your project's implementation in any way. With Narada you\ncan create any projects using any programming languages as long as your\nproject conform to Narada interface and work in \\*NIX.\n\nTypical example of project which wins a lot when managed by Narada is web\nsite backend or network service, which consists of several applications\n(even written in different programming languages) with different entry\npoints (HTTP, RPC, cron, email), which all should have common runtime\nenvironment, logs, etc.\n\nIn short, Narada dictates where your project should keep and how it should\nwork with: config files, logs, locks, temporary and persistent data files,\nrequired external configuration for cron, qmail, databases. All of this is\ncalled \"Narada interface\", and if your project conform to it then you can\nalso use a lot of handy command-line tools provided by Narada to deploy,\nbackup and manage your project.\n\nThere are few helper Narada::\\* modules for Perl which helps you to conform\nNarada interface in your Perl modules/scripts; for other languages you may\nwant to create similar helpers, but this isn't required - Narada interface\nis simple and can be easily conformed without using special helpers (it\nwas designed that way to make it ease to conform to Narada interface even\nin shell scripts).\n\nTo use Narada you'll also need to learn format of `.migrate` files used\nto describe project's upgrade/downgrade operations (see\n[\"SYNTAX\" in App::migrate](https://metacpan.org/pod/App::migrate#SYNTAX)) and choose which \"project template\" to use for\nyour new project (for ex. see default template\n[narada-base](https://github.com/powerman/narada-base); you can modify it\nwith plugins or develop your own template from scratch).\n\n## Main features\n\n- Templates and plugins for project source.\n\n    You can choose one of existing templates when starting new project, and\n    even modify some of them using plugins - or made your own templates or\n    plugins if you often develop similar projects. Both templates and plugins\n    are implemented by merging remote repositories, so if they will change\n    after you've started your project you can easily update it by fetching and\n    merging them again.\n\n- You can continue using your favorite workflow.\n\n    While [narada-new](https://metacpan.org/pod/narada-new) tool and existing project templates/plugins use Git,\n    you may opt out and don't use them. This is only Narada tool which do\n    something with your **project's source directory** (all other tools work\n    only with **project's deploy directory**) and it's completely optional. You\n    can create new project using Mercurial or even without using any VCS, and\n    use any workflow you like. All you need is produce `.migrate` and related\n    files as result of releasing every version of your project, including\n    ephemeral development versions which you may release many times per day.\n\n- Provide file/directory structure for deployed project.\n\n    Some choices are already made for you: where and how to store project\n    configuration, temporary and persistent data files, logs, locks, backups,\n    current version number. This file/directory structure was designed to make\n    it ease to use from any programming language (including shell scripts) and\n    provide several valuable features like reliable upgrades and backups.\n\n- Reliable project upgrade and downgrade.\n\n    Narada use `.migrate` files to describe operations needed to upgrade and\n    (required!) downgrade project. While usual development process you'll run\n    these operations each time you wanna check how your changes work, i.e.\n    this will happens dozens (if not hundreds) of times while you're\n    developing next version, so both upgrade and downgrade operations are\n    usually guaranteed to be well-tested before releasing each next version.\n\n- Different project installations have different configurations.\n\n    Changes in your local configuration won't be occasionally sent with next\n    update to production server. And you won't have any issues because of\n    config files added into your repo with project sources because in Narada\n    projects config files exists only in **project's deploy directory**.\n\n- Ease project setup after installation/update.\n\n    Narada provide tools to update project's external setup (cron tasks, qmail\n    handlers for incoming emails, MySQL scheme) according to current project's\n    configuration.\n\n- Reliable services.\n\n    Run your FastCGI or RPC daemons with guaranteed restart after crash.\n    Narada project may have own services, always running in background.\n    By default we use [runit](http://smarden.org/runit/) for supervising\n    project's services, but other similar supervisors like daemontools or s6\n    also can be used.\n\n- All project's applications have common log(s).\n\n    When your project consists of many applications/scripts or run many\n    processes of same application it's important to have single common log for\n    all of them. To implement this each Narada project usually run own log\n    service. By default we use [socklog](http://smarden.org/socklog/)\n    (syslog-compatible daemon) to receive logs from all project's applications\n    and `svlogd` tool from [runit](http://smarden.org/runit/) to manage logs\n    (rotate, filter, group records in separate files, etc.).\n\n- All project's applications have common lock.\n\n    This guarantee live project's consistency while backup, update or manual\n    maintenance. NOTE: While Narada provide and use this lock file in it's own\n    tools **it's your responsibility to always get shared lock on that lock\n    file before doing read/write of any project's files or databases** - if you\n    won't do this you'll break mentioned above consistency guarantee.\n\n- Consistent and fast project backup.\n\n    Narada interface include shared/exclusive project locking, which let us\n    guarantee backup consistency between project files and databases.\n\n    Narada backup tool support incremental backups both for files and\n    database, which makes it possible to backup most projects in few seconds -\n    your website visitors won't even notice your daily/hourly backup!\n\n- Backward compatibility.\n\n    Whenever possible, projects created using previous Narada versions will be\n    supported by latest Narada (but newly added tools may not work with such\n    an old projects).\n\n## Important changes since previous versions\n\n### Narada 1.x\n\nNarada 1 was created when Git and Mercurial wasn't exists yet, so it\ndoesn't use repository for project sources. Also it doesn't separate\nproject's source vs deploy directories and run project's applications in\ndirectory with it sources - this was perfectly fine for projects developed\nin script languages like Perl without using VCS. The `narada-new` tool\nused to create Narada 1 projects is still available but it was renamed to\n[narada-new-1](https://metacpan.org/pod/narada-new-1).\n\nAlso Narada 1 provide several tools used to generate, email/upload and\napply patches for project's directory - this was the way to both deploy\nnew version to server and distribute changes to other developers in team.\nThese tools has no use in current Narada, but they still exists for\ncompatibility with Narada 1 projects: [narada-diff](https://metacpan.org/pod/narada-diff), [narada-release](https://metacpan.org/pod/narada-release),\n[narada-patch-remote](https://metacpan.org/pod/narada-patch-remote), [narada-patch-send](https://metacpan.org/pod/narada-patch-send), [narada-patch-pull](https://metacpan.org/pod/narada-patch-pull),\n[narada-patch](https://metacpan.org/pod/narada-patch).\n\nFiles\u0026directories structure also was changed since Narada 1.x, see\n[Changes](https://metacpan.org/changes/distribution/Narada) in version\n2.0.0 for more details.\n\nThis documentation describe current Narada, check documentation for\n[latest Narada 1](https://metacpan.org/pod/release/POWERMAN/Narada-v1.4.5/lib/Narada.pm)\nif you're still using Narada 1 projects.\n\n# EXAMPLE\n\nCreate new project:\n\n    ~ $ narada-new hello_world\n    ... a lot of Git output skipped\n    ~ $ cd hello_world/\n    ~/hello_world $ ls -AF\n    build*  deploy*  doc/  .git/  .gitignore  migrate  release*  t/\n\nThis is **project's source directory** initialized using default template.\nIt provide basic `migrate` files with all commands needed to create all\nfiles/directories needed by every deployed Narada project plus few\nscripts: `./release` for releasing new versions (both development\nephemeral versions and tagged final versions) and `./deploy` for\ninstalling them into `_live/` subdirectory.\n\nCool, we already can release something!\n\n    ~/hello_world $ ./release\n    t/build/migrate.t .. 1/1 # Checking migrate\n    t/build/migrate.t .. ok\n    All tests successful.\n    Files=1, Tests=1,  0 wallclock secs ( ... )\n    Result: PASS\n    ~/hello_world $ ls -AF\n    build*  deploy*  doc/  .git/  .gitignore  migrate  release*  .release/\n    t/  VERSION\n    ~/hello_world $ ls -AF .release/\n    0.0.0+b4ff31c.migrate  0.0.0+b4ff31c.patch\n    ~/hello_world $ cat VERSION\n    0.0.0+b4ff31c\n\nAs you see, your project get unique ephemeral version number in file\n`VERSION` and this version was released as two files in `.release/`.\nNow, let's deploy it!\n\n    ~/hello_world $ ./deploy\n    Loading .release/0.0.0+b4ff31c.migrate\n    ... a lot of executed commands output skipped\n    Migration to 0.0.0+b4ff31c completed\n    ~/hello_world $ ls -AF\n    build*  deploy*  doc/  .git/  .gitignore  _live/  migrate  release*\n    .release/  t/  VERSION\n    ~/hello_world $ ls -AF _live/\n    .backup/  config/  doc/  .lock  .release/  t/  tmp/  var/  VERSION\n\nThe `_live/` is **project's deploy directory**. There are may be many of\nthem, even on same development machine in case you develop in several\nbranches and wanna have each branch deployed to separate directory, or\njust wanna install simultaneously old and new versions of project and\ncompare how they work.\n\nOkay, we get Narada files\u0026directories structure in `_live/`, but it\ndoesn't have much use for now. Let's add something to our project.\n\n    ~/hello_world $ cat \u003ehello \u003c\u003cEOF\n    \u003e #!/usr/bin/perl\n    \u003e print \"Hello, World!\\n\";\n    \u003e EOF\n    ~/hello_world $ chmod +x hello\n    ~/hello_world $ git add hello\n    ~/hello_world $ ./release \u0026\u0026 ./deploy\n    t/build/migrate.t .. 1/1 # Checking migrate\n    t/build/migrate.t .. ok\n    All tests successful.\n    Files=1, Tests=1,  0 wallclock secs ( ... )\n    Result: PASS\n    Loading .release/0.0.0+b4ff31c.dirty-1428492362.migrate\n    Loading .release/0.0.0+b4ff31c.migrate\n    Backuping to .backup/full-0.0.0+b4ff31c.tar\n    ...\n    Migration to 0.0.0 completed\n    ...\n    Migration to 0.0.0+b4ff31c.dirty-1428492362 completed\n\nWhat just happens? New ephemeral version \"0.0.0+b4ff31c.dirty-1428492362\"\nwas released (it have such a name because we didn't committed our changes\nto the repo yet); then previous version \"0.0.0+b4ff31c\" installed in\n`_live/` was saved in the backup and downgraded to version \"0.0.0\" (which\nis initial version meaning \"empty directory\"); then that empty directory\nwas upgraded to current version \"0.0.0+b4ff31c.dirty-1428492362\". Look:\n\n    ~/hello_world $ cat VERSION\n    0.0.0+b4ff31c.dirty-1428492362\n    ~/hello_world $ ls -AF .release/\n    0.0.0+b4ff31c.dirty-1428492362.migrate  0.0.0+b4ff31c.migrate\n    0.0.0+b4ff31c.dirty-1428492362.patch    0.0.0+b4ff31c.patch\n    ~/hello_world $ ls -AF _live/\n    .backup/  config/  doc/  hello*  .lock  .release/  t/  tmp/  var/\n    VERSION\n    ~/hello_world $ cd _live/\n    ~/hello_world/_live $ ./hello\n    Hello, World!\n    ~/hello_world/_live $ cd -\n    ~/hello_world $\n\nNext, let's start using some Narada features, like config files.\nWe'll also add migration operation to `migrate` file to create new config\nfile on upgrading to this version and remove it on downgrading from this\nversion.\n\n    ~/hello_world $ echo 'add_config my_name Powerman' \u003e\u003e migrate\n    ~/hello_world $ cat \u003ehello \u003c\u003cEOF\n    \u003e #!/usr/bin/perl\n    \u003e use Narada::Config qw( get_config_line );\n    \u003e printf \"Hello, %s!\\n\", get_config_line('my_name');\n    \u003e EOF\n    ~/hello_world $ ./release \u0026\u0026 ./deploy\n    ...\n    Loading .release/0.0.0+b4ff31c.dirty-1428493197.migrate\n    Loading .release/0.0.0+b4ff31c.dirty-1428492362.migrate\n    Backuping to .backup/full-0.0.0+b4ff31c.dirty-1428492362.tar\n    ...\n    Migration to 0.0.0 completed\n    ...\n    Migration to 0.0.0+b4ff31c.dirty-1428493197 completed\n    ~/hello_world $ cd _live/\n    ~/hello_world/_live $ ./hello\n    Hello, Powerman!\n\nIn deploy directory we can safely modify config or data files - these\nchanges will affect only project deployed in this directory.\n\n    ~/hello_world/_live $ ls -AF config/\n    backup/  crontab/  log/  my_name  mysql/  qmail/\n    ~/hello_world/_live $ echo Anonymous \u003e config/my_name\n    ~/hello_world/_live $ ./hello\n    Hello, Anonymous!\n    ~/hello_world/_live $ cd -\n    ~/hello_world $\n\nNow, let's release current version tagged with own version number.\n\n    ~/hello_world $ git add migrate\n    ~/hello_world $ git commit -m 'add hello'\n    ~/hello_world $ ./release --minor\n    t/build/migrate.t .. 1/1 # Checking migrate\n    t/build/migrate.t .. ok\n    All tests successful.\n    Files=1, Tests=1,  0 wallclock secs ( ... )\n    Result: PASS\n    [master 8338faa] Release 0.1.0\n     1 file changed, 4 insertions(+)\n    ~/hello_world $ cat VERSION\n    0.1.0\n    ~/hello_world $ ls -AF .release/\n    0.0.0+b4ff31c.dirty-1428492362.migrate  0.0.0+b4ff31c.migrate\n    0.0.0+b4ff31c.dirty-1428492362.patch    0.0.0+b4ff31c.patch\n    0.0.0+b4ff31c.dirty-1428493197.migrate  0.1.0.migrate\n    0.0.0+b4ff31c.dirty-1428493197.patch    0.1.0.patch\n    ~/hello_world $\n\nAnd deploy it on server:\n\n    ~/hello_world $ ssh localhost 'mkdir -p hello_project/.release'\n    ~/hello_world $ scp .release/0.1.0.* localhost:hello_project/.release/\n    0.1.0.migrate        100% 7105     6.9KB/s   6.9KB/s   00:00\n    0.1.0.patch          100% 5223     5.1KB/s   6.9KB/s   00:00\n    ~/hello_world $ ssh localhost\n    ~ $ cd hello_project/\n    ~/hello_project $ ls -AF\n    .release/\n    ~/hello_project $ ls -AF .release/\n    0.1.0.migrate  0.1.0.patch\n    ~/hello_project $ narada-install 0.1.0\n    Loading .release/0.1.0.migrate\n    ...\n    Migration to 0.1.0 completed\n    ~/hello_project $ ls -AF\n    .backup/  config/  doc/  hello*  .lock  .release/  t/  tmp/  var/\n    VERSION\n    ~/hello_project $ ./hello\n    Hello, Powerman!\n    ~/hello_project $\n\nFinally, let's cleanup and uninstall all projects.\n\nTemplate used to create this project include some basic cron configuration\nto make daily project backups. And these settings was already added to\nyour user's crontab while installing the project. So, before removing\nproject directories we should remove this cron setup.\n\n    ~/hello_project $ narada-setup-cron --clean\n    ~/hello_project $ cd ..\n    ~ $ rm -rf hello_project/\n    ~ $ exit\n    ~/hello_world $ cd _live/\n    ~/hello_world/_live $ narada-setup-cron --clean\n    ~/hello_world/_live $ cd ../..\n    ~ $ rm -rf hello_world/\n\n# INTERFACE\n\nThe \"Narada interface\" is described here files\u0026directories structure for\n**project's deploy directory** and some conventions about how they should\nbe used. Your project must conform to this interface.\n\n\u003e For example, let's review part of Narada interface related to\n\u003e [\"Consistent and fast project backup.\"](#consistent-and-fast-project-backup) feature.\n\u003e\n\u003e \"Consistent\" require using shared/exclusive file locking on file\n\u003e `.lock`. All Narada does is create that file while installing new\n\u003e project and acquire exclusive lock on it while executing [narada-backup](https://metacpan.org/pod/narada-backup).\n\u003e But to really have consistent backups **you** must acquire shared lock on\n\u003e that file when accessing any project files or database in any of your\n\u003e applications! In Perl scripts you can use helper module [Narada::Lock](https://metacpan.org/pod/Narada::Lock), and\n\u003e it's not a big deal to manually use flock(2) in any other language. If you\n\u003e fail to do this, you backups won't be guaranteed to be consistent anymore!\n\u003e\n\u003e \"Fast\" consists of two parts: files and database. To backup project files\n\u003e fast you should keep large junk files according to Narada's interface -\n\u003e in directories listed in `config/backup/exclude`, for ex. in `tmp/`.\n\u003e To backup MySQL database fast you should try hard to store large amount of\n\u003e data in append-only tables with \"auto\\_increment primary key\", and add\n\u003e names of these tables to `config/mysql/dump/incremental`.\n\u003e\n\u003e All of this will let [narada-backup](https://metacpan.org/pod/narada-backup) to hold exclusive lock (and thus\n\u003e freeze your project while backup) shortest possible time, complete safe\n\u003e part of backup task after releasing the lock, and use incremental backups\n\u003e to save both time and disk space.\n\n## Directory types\n\nThere are two types of \"root\" directories in your project:\n**source directory** and **deploy directory**.\n\nThe **project's source directory** isn't part of Narada interface.\nOnly tool which work with it is [narada-new](https://metacpan.org/pod/narada-new) (which helps you to create\nnew project), but you're not required to use it, and even if you use it no\nNarada tools will touch your **project's source directory** after it will\nbe created.\n\nThe **project's deploy directory** is the one where all files\u0026directories\ndefined by Narada interface should exists. Also **it's the directory where\nyou should run all Narada tools and your project's applications** - this is\nrequired to allow them to find all Narada files\u0026directories using paths \nrelative to current directory.\n\nIt's ok to have many source directories (as repo clones for your team) and\nto have many deploy directories (as different installations on same or\ndifferent computers) - for ex. it may be very useful to deploy different\nversions from different Git branches to different deploy directories on\nsame development machine.\n\n## Overview of deploy directory structure\n\nProject templates often include typical directories like `doc/` or `t/`\nbut they isn't part of Narada interface and thus you're free to rename or\nremove them if you like.\n\n- `.release/`\n\n    Contain `.migrate` and related files used to upgrade and downgrade\n    project while migrating to another version.\n\n- `.backup/`\n\n    Contain project backups. You can create and manage them yourself, but they\n    also will be automatically created before migrating to another version and\n    may be automatically used when only way to downgrade project is restore\n    previous version from backup. In general it's safe to remove backups when\n    you like, but absence of some backups may make it impossible to downgrade\n    to some previous version.\n\n- `VERSION`\n\n    Contain current project version. Required for upgrade and downgrade, and\n    will be automatically updated after migration or restoring from backup.\n    May be useful for your applications (read-only).\n\n- `.lock*`\n\n    Several lock files used mostly internally by Narada tools, except for\n    the `.lock` file which should be shared-locked by all your applications\n    while they read or write any project's files or databases.\n\n- `config/`\n\n    Project's configuration (both defined by Narada interface and custom\n    settings of your project). May differ in different project's deploy\n    directories. While it's possible to modify configuration in all deploy\n    directories while project migration, usually most of config files modified\n    either manually or by your applications in one deploy directory.\n\n- `service/`\n\n    Used to setup project's services (daemons) and run them using service\n    supervisor (runit, daemontools, etc.). Most projects usually have just one\n    (log) or a couple (log and fastcgi/http/rpc) services.\n\n- `tmp/`\n\n    Used for temporary data files. Contents of this directory won't be\n    included in backups.\n\n- `var/`\n\n    Used for persistent data files.\n\n## Deploy\n\nIn [\"EXAMPLE\"](#example) above you've seen scripts `./release`, `./deploy`, files\n`migrate` and `VERSION`, directories `.release/` and `_live/` while\nworking with Narada, but all of them was in **project's source directory**\nand isn't part of Narada interface! All of them was provided by used\nproject template, and different templates may implement these tasks in\ndifferent ways - read documentation for chosen project template. Also\nyou're free to modify these paths and scripts in any way - template\nprovide only starting point, but it's your project's sources and you have\nfreedom to do anything you like.\n\nWhat is actually part of Narada interface is result of running these\n`./release \u0026\u0026 ./deploy` scripts: file `.release/\u003cversion\u003e.migrate`\nand optional related files (usually named `.release/\u003cversion\u003e.patch`\nor `.release/\u003cversion\u003e.tgz`) in **project's deploy directory**.\nNo matter how you develop, build, compile, release and copy/upload new\nversion to deploy directory, the final result should be such file/files.\n\n- `.release/\u003cversion\u003e.migrate`\n\n    These files must contain upgrade and downgrade operations between version\n    previous to `\u003cversion\u003e` and `\u003cversion\u003e`, but usually they also\n    contain operations for all previous versions up to initial version \"0.0.0\"\n    (meaning \"empty directory\").\n\n    It's recommended to use [semantic versions](http://semver.org/), but\n    except for predefined initial version \"0.0.0\" you're free to use for your\n    project any version numbering scheme you like.\n\n    Files\u0026directories structure conforming to Narada interface must be created\n    using upgrade operations in this file when describing upgrade from version\n    \"0.0.0\".\n\n    Narada uses [App::migrate](https://metacpan.org/pod/App::migrate) to implement project migrations, format of\n    `.migrate` files is documented in [\"SYNTAX\" in App::migrate](https://metacpan.org/pod/App::migrate#SYNTAX).\n\n    \u003e     **When you need to convert some data in files or database when installing\n    \u003e     new version you should use** `.migrate` **file to run scripts which will\n    \u003e     do this.**\n    \u003e\n    \u003e     You should not try to do these data migrations automatically on first time\n    \u003e     new version of your project's application starts - both because this will\n    \u003e     make impossible to downgrade quickly and without losing data (if you'll\n    \u003e     provide script which does backward data conversion, of course) and you'll\n    \u003e     have to restore from backup instead, and because project migration may\n    \u003e     include many upgrades at once and your application as it was at one of\n    \u003e     intermediate versions wasn't get a chance to run at all.\n\n## Backup\n\n- `config/backup/exclude`\n\n    Shell patterns (one per line) for files/dirs which shouldn't be included\n    in backup. Must contain at least these lines:\n\n        ./.backup/*         to avoid recursively including old backups in new\n        ./.lock*            to avoid unlocking while restoring from backup\n        ./tmp/*             to conform to Narada interface and not include\n                            temporary files in backups\n\n- `config/mysql/dump/incremental`\n\n    List of database tables (one per line) which can be dumped incrementally\n    (according to their \"auto\\_increment primary key\" field). `narada-backup`\n    will dump only new records in these tables (dumps for older records will\n    be available in existing files in `.backup/` or `var/mysql/`).\n\n- `config/mysql/dump/empty`\n\n    List of database tables (one per line) which records shouldn't be included in\n    backup, only scheme.\n\n- `config/mysql/dump/ignore`\n\n    List of database tables (one per line) which shouldn't be included in\n    backup at all (even scheme).\n\n- `var/mysql/`\n\n    Contain files with last database dump (usually made while last backup).\n\n- `var/use/`\n\n    Keeps current used/unused state recorded by last run of `narada-setup-*`\n    and `narada-*-services` tools. It will be used by [narada-restore](https://metacpan.org/pod/narada-restore) to\n    setup project after full restore.\n\n- `.backup/full.tar`\n- `.backup/incr.tar`\n\n    Latest full and incremental backups. To force full backup next time just\n    remove `.backup/full.tar`. See [narada-backup](https://metacpan.org/pod/narada-backup) for more details.\n\n## Logging\n\n- `config/log/type`\n\n    Define type of logging: `syslog` (default if this file not exists) or\n    `file`. If set to `syslog` then `config/log/output` should contain path\n    to syslog's UNIX socket (like `var/log.sock` or `/dev/log`).\n\n    It's recommended to use `syslog` type and run syslog-compatible log\n    service for each project, because it's very hard to correctly implement\n    concurrent writes to common log file.\n\n    If set to `file` then each application in your project must open this\n    file in append-only mode, avoid writing single log record using more than\n    one write syscall (may happens because of buffered I/O), don't use NFS for\n    `var/log/`… and you anyway may have some issues. One possible issue is\n    performance: if you'll conform to Narada interface and acquire shared lock\n    on `.lock` before writing each one line to log this may result in\n    noticeable slowdown. Another possible issue happens if you avoid locking\n    because of performance issue, but without locks it may be impossible to\n    ensure log consistency in backups or reliably implement log rotation.\n\n- `config/log/output`\n\n    File name where project applications should write their logs: either UNIX\n    socket (to syslog-compatible daemon) or usual file (or `/dev/stdout`).\n\n- `config/log/level`\n\n    Current log level, should be one of these strings:\n\n        ERR WARN NOTICE INFO DEBUG DUMP\n\n- `var/log/`\n\n    This directory contains project log files.\n\n## Cron tasks\n\n- `config/crontab/*`\n\n    Settings for project's cron tasks, in crontab format.\n\n    When these settings will be installed to system's cron, each command will\n    be automatically prefixed by:\n\n        cd /path/to/project/deploy/dir || exit;\n\n    `narada-setup-cron` update system's cron using settings from these files.\n\n## Processing incoming emails\n\nOnly qmail supported at this time.\n\n- `config/qmail/*`\n\n    Files with qmail configuration (in .qmail format).\n    Commands listed in these files (lines beginning with `|`) will be\n    executed in **project's deploy directory** instead of user's home directory\n    (qmail's default behaviour).\n\n- `var/qmail/*`\n\n    Internally used by `narada-setup-qmail`.\n\n## Database\n\nOnly MySQL supported at this time.\n\n- `config/mysql/db`\n\n    Contains one line - name of MySQL database. If this file doesn't exists or\n    empty - Narada won't use database.\n\n- `config/mysql/login`\n- `config/mysql/pass`\n\n    Login/pass for database.\n\n- `config/mysql/host`\n\n    Host name of database server. if this file doesn't exists or empty then\n    usual UNIX socket will be used to connect to MySQL server.\n\n- `config/mysql/port`\n\n    TCP port of database server.\n\n## Locking\n\n- `.lock`\n\n    This file should be shared-locked using flock(2) or [Narada::Lock](https://metacpan.org/pod/Narada::Lock) or\n    [narada-lock](https://metacpan.org/pod/narada-lock) before accessing any project's files or database by usual\n    applications, and exclusive-locked while project's backup, update or\n    manual maintenance.\n\n- `.lock.new`\n\n    This file will be created before trying to acquire exclusive lock on\n    `.lock`. All applications wanted to acquire shared lock on `.lock` must\n    check before that is `.lock.new` exists and if yes then delay/avoid\n    locking `.lock`. This is needed to guarantee exclusive lock will be\n    acquired as soon as possible.\n\n    After exclusive lock will be acquired and critical operations requiring it\n    will be completed - `.lock.new` will be removed.\n\n    If server will be rebooted while waiting for exclusive lock or in the\n    middle of critical operations requiring it then file `.lock.new`\n    won't be removed and project applications won't continue to work after\n    server reboot until this file will be removed manually or another\n    operation requiring exclusive lock will be started and successfully\n    finished.\n\n- `.lock.bg`\n\n    Each project's background process (running as service, or started by cron,\n    qmail, etc.) should acquire shared lock on this file. This can be easily\n    done using [narada-bg](https://metacpan.org/pod/narada-bg) tool. This will make possible to reliably detect\n    and kill all project's background processes while upgrade or downgrade\n    using [narada-bg-killall](https://metacpan.org/pod/narada-bg-killall) tool.\n\n## Services\n\nThere are several ways to start project's services: manually by running\n[narada-start-services](https://metacpan.org/pod/narada-start-services) - this way they wasn't start automatically after\nserver reboot, try to start them every 1 minute from cron if they wasn't\nrunning yet (usually using `config/crontab/service` but this file isn't\npart of Narada interface) - this way it may took about 1 minute before\nproject services will be started after deploy or server reboot, run them\nas one of system-wide service based on similar (runit/daemontools/s6/etc.)\nsupervisor - fastest and most reliable way but require root permissions to\nadd new system-wide service.\n\n- `config/service/type`\n\n    Type of used service supervisor. For now only supported type is `runit`.\n\n- `.lock.service`\n\n    This lock file is used by [narada-start-services](https://metacpan.org/pod/narada-start-services) to check is services\n    already running.\n\n# TOOLS\n\nAll tools (except [narada-new](https://metacpan.org/pod/narada-new)) must be executed in\n**project's deploy directory**. Read man pages of these tools for details.\n\n## Create new project\n\n- [narada-new](https://metacpan.org/pod/narada-new)\n\n## Deploy \u0026 uninstall\n\n- [narada-install](https://metacpan.org/pod/narada-install)\n- [narada-setup-cron](https://metacpan.org/pod/narada-setup-cron)\n- [narada-setup-mysql](https://metacpan.org/pod/narada-setup-mysql)\n- [narada-setup-qmail](https://metacpan.org/pod/narada-setup-qmail)\n- [narada-shutdown-services](https://metacpan.org/pod/narada-shutdown-services)\n- [narada-start-services](https://metacpan.org/pod/narada-start-services)\n\n## Backup \u0026 restore\n\n- [narada-backup](https://metacpan.org/pod/narada-backup)\n- [narada-mysqldump](https://metacpan.org/pod/narada-mysqldump)\n- [narada-restore](https://metacpan.org/pod/narada-restore)\n\n## Background processes\n\n- [narada-bg](https://metacpan.org/pod/narada-bg)\n- [narada-bg-killall](https://metacpan.org/pod/narada-bg-killall)\n- [narada-lock](https://metacpan.org/pod/narada-lock)\n- [narada-lock-exclusive](https://metacpan.org/pod/narada-lock-exclusive)\n\n## Misc tools\n\n- [narada-viewlog](https://metacpan.org/pod/narada-viewlog)\n- [narada-mysql](https://metacpan.org/pod/narada-mysql)\n- [narada-emu](https://metacpan.org/pod/narada-emu)\n\n## SSH tools\n\nThese tools make it easier to copy files between local and remote\nproject's deploy directories. If you're doing things in right way - you\nwon't need these tools.\n\n- [narada-remote](https://metacpan.org/pod/narada-remote)\n- [narada-upload](https://metacpan.org/pod/narada-upload)\n- [narada-download](https://metacpan.org/pod/narada-download)\n\n## Perl modules\n\n- [Narada::Config](https://metacpan.org/pod/Narada::Config)\n- [Narada::Lock](https://metacpan.org/pod/Narada::Lock)\n- [Narada::Log](https://metacpan.org/pod/Narada::Log)\n\n# SUPPORT\n\n## Bugs / Feature Requests\n\nPlease report any bugs or feature requests through the issue tracker\nat [https://github.com/powerman/Narada/issues](https://github.com/powerman/Narada/issues).\nYou will be notified automatically of any progress on your issue.\n\n## Source Code\n\nThis is open source software. The code repository is available for\npublic review and contribution under the terms of the license.\nFeel free to fork the repository and submit pull requests.\n\n[https://github.com/powerman/Narada](https://github.com/powerman/Narada)\n\n    git clone https://github.com/powerman/Narada.git\n\n## Resources\n\n- MetaCPAN Search\n\n    [https://metacpan.org/search?q=Narada](https://metacpan.org/search?q=Narada)\n\n- CPAN Ratings\n\n    [http://cpanratings.perl.org/dist/Narada](http://cpanratings.perl.org/dist/Narada)\n\n- AnnoCPAN: Annotated CPAN documentation\n\n    [http://annocpan.org/dist/Narada](http://annocpan.org/dist/Narada)\n\n- CPAN Testers Matrix\n\n    [http://matrix.cpantesters.org/?dist=Narada](http://matrix.cpantesters.org/?dist=Narada)\n\n- CPANTS: A CPAN Testing Service (Kwalitee)\n\n    [http://cpants.cpanauthors.org/dist/Narada](http://cpants.cpanauthors.org/dist/Narada)\n\n# AUTHOR\n\nAlex Efros \u003cpowerman@cpan.org\u003e\n\n# CONTRIBUTORS\n\nNikita Savin \u003casdfgroup@gmail.com\u003e\n\nNick Levchenko \u003cproject129@yandex.ru\u003e\n\n# COPYRIGHT AND LICENSE\n\nThis software is Copyright (c) 2008- by Alex Efros \u003cpowerman@cpan.org\u003e.\n\nThis is free software, licensed under:\n\n    The MIT (X11) License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpowerman%2Fnarada","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpowerman%2Fnarada","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpowerman%2Fnarada/lists"}