[MediaWiki-commits] [Gerrit] Update to service-template-node v0.1.3 - change (mediawiki...graphoid)
Mobrovac has submitted this change and it was merged.
Change subject: Update to service-template-node v0.1.3
..
Update to service-template-node v0.1.3
Change-Id: Icab18289fb220a3e5df033352faa3b3294d9d04f
---
M .gitignore
M doc/README.md
M doc/commands.md
A doc/deployment.md
M doc/template.md
M package.json
A targets.yaml
7 files changed, 194 insertions(+), 16 deletions(-)
Approvals:
Mobrovac: Verified; Looks good to me, approved
diff --git a/.gitignore b/.gitignore
index a359b3f..978f2d1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
.idea
graphoid.iml
+Dockerfile
coverage
config.yaml
node_modules
diff --git a/doc/README.md b/doc/README.md
index 26adc44..d837f0a 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -8,6 +8,7 @@
3. [Configuration](config.md)
4. [Useful Commands](commands.md)
5. [Coding Guide](coding.md)
+6. [Deployment](deployment.md)
Have fun while creating RESTful API services!
diff --git a/doc/commands.md b/doc/commands.md
index e1bc803..01b6c5a 100644
--- a/doc/commands.md
+++ b/doc/commands.md
@@ -95,3 +95,7 @@
After you log out completely and log back in, you should be able to run the
above scripts without resorting to `sudo`.
+## Deployment
+
+See [this document](deployment.md) for how to get ready to deploy your service.
+
diff --git a/doc/deployment.md b/doc/deployment.md
new file mode 100644
index 000..bb93f7d
--- /dev/null
+++ b/doc/deployment.md
@@ -0,0 +1,164 @@
+# Deployment
+
+Getting your service ready to be deployed on WMF production machines involves
+several tasks. This document explains the steps needed to get started and how
to
+keep your deployable copy up-to-date.
+
+## Repositories
+
+Because Node.js services use npm dependencies which can be binary, these need
to
+be pre-built. Therefore, two repositories are needed; one for the source code
of
+your service, and the other, so-called *deploy* repository. Both should be
+available as WM's Gerrit repositories with the paths
+*mediawiki/services/your-service-name* and
+*mediawiki/services/your-service-name/deploy*. When [requesting
+them](https://www.mediawiki.org/wiki/Git/New_repositories/Requests) ask for the
+former to be a clone of [the service
+template](https://github.com/wikimedia/service-template-node) and the latter to
+be empty.
+
+It is important to note that the deploy repository is only to be updated
+directly before (re-)deploying the service, and not on each patch merge
entering
+the *master* branch of the regular repository. In other words, **the deploy
+repository mirrors the code deployed in production at all times**.
+
+The remainder of the document assumes these two repositories have been created
+and that you have cloned them using your Gerrit account, i.e. not anonymously,
+with the following outline:
+
+```
+~/code/
+ |- your-service
+ -- deploy
+```
+
+Furthermore, it is assumed that you have initialised the deploy repository:
+
+```bash
+$ cd ~/code/deploy
+$ git review -s
+$ touch README.md
+$ git add README.md
+$ git commit -m Initial commit
+$ git push -u origin master # or git review -R if this fails
+# go to Gerrit and +2 your change, if needed and then:
+$ git pull
+```
+
+Finally, if you haven't yet done so, do [basic service
+configuration](config.md).
+
+The remainder of the document refers to these two repositories as the *source
+repository* and the *deploy repository*, respectively.
+
+## Configuration
+
+The service template includes an automation script which updates the deploy
+repository, but it needs to be configured properly in order to work.
+
+### package.json
+
+The first part of the configuration involves keeping your source repository's
+`package.json` updated. Look for its [deploy stanza](../package.json#L49).
+Depending on the exact machine on which your service will be deployed, you may
+need to set `target` to either `ubuntu` or `debian`.
+
+The important thing is keeping the `dependencies` field up to date at all
times.
+There you should list all of the extra packages that are needed in order to
+build the npm module dependencies. The `_all` field denotes packages which
+should be installed regardless of the target distribution, but you can add
+other, distribution-specific package lists, e.g.:
+
+```javascript
+deploy: {
+ target: ubuntu,
+ dependencies: {
+ubuntu: [pkg1, pkg2],
+debian: [pkgA, pkgB],
+_all: [pkgOne, pkgTwo]
+ }
+}
+```
+
+In this example, with the current configuration, packages *pkg1*, *pkg2*,
+*pkgOne* and *pkgTwo* are going to be installed before building the
+dependencies. If, instead, the target is changed to `debian`, then *pkgA*,
+*pkgB*, *pkgOne* and *pkgTwo* are selected.
+
+As a rule of thumb, **whenever you need to install extra packages into your
+development environment for satisfying node module dependencies, add them to
+*deploy.dependencies* to ensure the successful build and update of the deploy
[MediaWiki-commits] [Gerrit] Update to service-template-node v0.1.3 - change (mediawiki...graphoid)
Mobrovac has uploaded a new change for review.
https://gerrit.wikimedia.org/r/205563
Change subject: Update to service-template-node v0.1.3
..
Update to service-template-node v0.1.3
Change-Id: Icab18289fb220a3e5df033352faa3b3294d9d04f
---
M .gitignore
M doc/README.md
M doc/commands.md
A doc/deployment.md
M doc/template.md
M package.json
A targets.yaml
7 files changed, 194 insertions(+), 16 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/services/graphoid
refs/changes/63/205563/1
diff --git a/.gitignore b/.gitignore
index a359b3f..978f2d1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
.idea
graphoid.iml
+Dockerfile
coverage
config.yaml
node_modules
diff --git a/doc/README.md b/doc/README.md
index 26adc44..d837f0a 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -8,6 +8,7 @@
3. [Configuration](config.md)
4. [Useful Commands](commands.md)
5. [Coding Guide](coding.md)
+6. [Deployment](deployment.md)
Have fun while creating RESTful API services!
diff --git a/doc/commands.md b/doc/commands.md
index e1bc803..01b6c5a 100644
--- a/doc/commands.md
+++ b/doc/commands.md
@@ -95,3 +95,7 @@
After you log out completely and log back in, you should be able to run the
above scripts without resorting to `sudo`.
+## Deployment
+
+See [this document](deployment.md) for how to get ready to deploy your service.
+
diff --git a/doc/deployment.md b/doc/deployment.md
new file mode 100644
index 000..bb93f7d
--- /dev/null
+++ b/doc/deployment.md
@@ -0,0 +1,164 @@
+# Deployment
+
+Getting your service ready to be deployed on WMF production machines involves
+several tasks. This document explains the steps needed to get started and how
to
+keep your deployable copy up-to-date.
+
+## Repositories
+
+Because Node.js services use npm dependencies which can be binary, these need
to
+be pre-built. Therefore, two repositories are needed; one for the source code
of
+your service, and the other, so-called *deploy* repository. Both should be
+available as WM's Gerrit repositories with the paths
+*mediawiki/services/your-service-name* and
+*mediawiki/services/your-service-name/deploy*. When [requesting
+them](https://www.mediawiki.org/wiki/Git/New_repositories/Requests) ask for the
+former to be a clone of [the service
+template](https://github.com/wikimedia/service-template-node) and the latter to
+be empty.
+
+It is important to note that the deploy repository is only to be updated
+directly before (re-)deploying the service, and not on each patch merge
entering
+the *master* branch of the regular repository. In other words, **the deploy
+repository mirrors the code deployed in production at all times**.
+
+The remainder of the document assumes these two repositories have been created
+and that you have cloned them using your Gerrit account, i.e. not anonymously,
+with the following outline:
+
+```
+~/code/
+ |- your-service
+ -- deploy
+```
+
+Furthermore, it is assumed that you have initialised the deploy repository:
+
+```bash
+$ cd ~/code/deploy
+$ git review -s
+$ touch README.md
+$ git add README.md
+$ git commit -m Initial commit
+$ git push -u origin master # or git review -R if this fails
+# go to Gerrit and +2 your change, if needed and then:
+$ git pull
+```
+
+Finally, if you haven't yet done so, do [basic service
+configuration](config.md).
+
+The remainder of the document refers to these two repositories as the *source
+repository* and the *deploy repository*, respectively.
+
+## Configuration
+
+The service template includes an automation script which updates the deploy
+repository, but it needs to be configured properly in order to work.
+
+### package.json
+
+The first part of the configuration involves keeping your source repository's
+`package.json` updated. Look for its [deploy stanza](../package.json#L49).
+Depending on the exact machine on which your service will be deployed, you may
+need to set `target` to either `ubuntu` or `debian`.
+
+The important thing is keeping the `dependencies` field up to date at all
times.
+There you should list all of the extra packages that are needed in order to
+build the npm module dependencies. The `_all` field denotes packages which
+should be installed regardless of the target distribution, but you can add
+other, distribution-specific package lists, e.g.:
+
+```javascript
+deploy: {
+ target: ubuntu,
+ dependencies: {
+ubuntu: [pkg1, pkg2],
+debian: [pkgA, pkgB],
+_all: [pkgOne, pkgTwo]
+ }
+}
+```
+
+In this example, with the current configuration, packages *pkg1*, *pkg2*,
+*pkgOne* and *pkgTwo* are going to be installed before building the
+dependencies. If, instead, the target is changed to `debian`, then *pkgA*,
+*pkgB*, *pkgOne* and *pkgTwo* are selected.
+
+As a rule of thumb, **whenever you need to install extra packages into your
+development environment for satisfying node module dependencies, add them to
