diff --git a/Dockerfile b/Dockerfile index d7f4bd0..e60821a 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,5 @@ FROM sparkfabrik/docker-locke-server:latest -MAINTAINER Paolo Pustorino +LABEL maintainer="Paolo Pustorino " # Remove content folder RUN rm -rf content/ @@ -7,5 +7,7 @@ RUN rm -rf content/ # Copy content and configuration COPY ./custom/config.js /srv/locke/config.js COPY ./custom/custom-styles.css /srv/locke/themes/spark/public/styles/custom.css +COPY ./custom/templates/page.html /srv/locke/themes/spark/templates/page.html +COPY ./custom/templates/layout.html /srv/locke/themes/spark/templates/layout.html COPY ./content /srv/locke/content COPY ./assets /srv/locke/assets diff --git a/README.md b/README.md index 26c89b6..b46f719 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,13 @@ -## SparkFabrik dockerized Raneto-based playbook +## SparkFabrik playbook -This repository contains our company playbook (and possibly all the knowledge around our company-wide practices and policies), packed with a Raneto container to consult them. -Ideal destination for this stuff is on a domain like **playbook.sparkfabrik.com**. So far you can `docker-compose up -d` and visit http://playbook.sparkfabrik.loc to enjoy the result. +This repository contains our [company playbook](https://playbook.sparkfabrik.com) (and possibly all the knowledge around our company-wide practices and policies), packed with a Raneto container to consult them. ## Contributions -So far the project is meant to be internal. All company members can download the project and provide merge-requests towards `master` branch. -The naming convention for the branches is: +So far the project is meant to be internal, all company members can clone the project and set up a local environment with the command `docker-compose up -d`. +After that, a local instance of the playbook will be available at `http://playbook.sparkfabrik.loc`. + +To contribute provide pull-requests towards `master` branch. The naming convention for the branches is: * `section/section-slug-title` for new sections (hardly they will be open by a company member, mostly it will be a matter of pre-made structure, but suggestions are welcome) * `content/description-of-the-content` for content contributions of various nature, like typo corrections, adding a new procedure or policy, etc diff --git a/assets/images/recipes/drupal-8-development-workflow.png b/assets/images/procedures/drupal-8-development-workflow.png similarity index 100% rename from assets/images/recipes/drupal-8-development-workflow.png rename to assets/images/procedures/drupal-8-development-workflow.png diff --git a/assets/images/procedures/local-development-environment--depiction-linux.png b/assets/images/procedures/local-development-environment--depiction-linux.png new file mode 100644 index 0000000..dd548da Binary files /dev/null and b/assets/images/procedures/local-development-environment--depiction-linux.png differ diff --git a/assets/images/procedures/local-development-environment--depiction-macosx.png b/assets/images/procedures/local-development-environment--depiction-macosx.png new file mode 100644 index 0000000..ecb3303 Binary files /dev/null and b/assets/images/procedures/local-development-environment--depiction-macosx.png differ diff --git a/assets/images/procedures/nm-allusers.png b/assets/images/procedures/nm-allusers.png new file mode 100644 index 0000000..2013c59 Binary files /dev/null and b/assets/images/procedures/nm-allusers.png differ diff --git a/assets/images/procedures/nm-openvpn-select.png b/assets/images/procedures/nm-openvpn-select.png new file mode 100644 index 0000000..2fe4e65 Binary files /dev/null and b/assets/images/procedures/nm-openvpn-select.png differ diff --git a/assets/images/procedures/nm-select.png b/assets/images/procedures/nm-select.png new file mode 100644 index 0000000..aae0698 Binary files /dev/null and b/assets/images/procedures/nm-select.png differ diff --git a/assets/images/procedures/nm-vpn-connected.png b/assets/images/procedures/nm-vpn-connected.png new file mode 100644 index 0000000..93e5318 Binary files /dev/null and b/assets/images/procedures/nm-vpn-connected.png differ diff --git a/assets/images/recipes/local-development-environment--depiction-linux.png b/assets/images/recipes/local-development-environment--depiction-linux.png deleted file mode 100644 index 5611aa2..0000000 Binary files a/assets/images/recipes/local-development-environment--depiction-linux.png and /dev/null differ diff --git a/assets/images/recipes/local-development-environment--depiction-macosx.png b/assets/images/recipes/local-development-environment--depiction-macosx.png deleted file mode 100644 index e22d83c..0000000 Binary files a/assets/images/recipes/local-development-environment--depiction-macosx.png and /dev/null differ diff --git a/content/FAQ/can-i-have.md b/content/FAQ/can-i-have.md index 33df0f2..a8fe299 100644 --- a/content/FAQ/can-i-have.md +++ b/content/FAQ/can-i-have.md @@ -3,7 +3,7 @@ Yes. We have budgets for Linux PCs, Apple machines, PHPStorm licenses and some more gizmos that you may need. Other than that, if you need a device or license to speed up your work, just ask your team leader and we'll evaluate case by case. -On standard hardware and software, please read [this section](/our-company/approved-hardware-and-software) to learn more. +On standard hardware and software, please read [this section](/tools-and-polices/approved-hardware-and-software) to learn more. ### Books diff --git a/content/FAQ/sort b/content/FAQ/sort index e373ee6..abdfb05 100644 --- a/content/FAQ/sort +++ b/content/FAQ/sort @@ -1 +1 @@ -50 +60 diff --git a/content/cookie-policy.md b/content/cookie-policy.md new file mode 100644 index 0000000..ad1a2af --- /dev/null +++ b/content/cookie-policy.md @@ -0,0 +1,61 @@ +/* +Description: Company Playbook cookie policy +*/ + +Last updated: January 2020 + +### WHAT ARE COOKIES? +The website **playbook.sparkfabrik.com** uses cookies. Pursuant to the FAQ of the Italian Data Protection Authority, issued on December 2012, available at www.garanteprivacy.it, cookies are "small text files" – made of letters and numbers - "that the websites visited by the user send to the device of the user (usually to the browser), where they are saved and then sent again to the website on the user’s subsequent visits". The cookies are used to simplify the analysis of the web traffic, to report when the Site or a specific section of the Site has been visited, to distinguish the users in order to provide personalized contents, and to help the Site’s administrators to improve the browsing experience for the users. + +Even though cookies are saved on the user’s device, they cannot be used to access the information stored on such device. Cookies cannot upload any kind of codes, carry computer viruses or malware and are not harmful for the user’s device. + +Hereinafter you may find additional information on the cookies installed on this site, and all necessary information in order to manage your preferences accordingly. + +### USERS' CONSENT +When you access for the first time to one of the pages of the site **playbook.sparkfabrik.com** you will see a short notice explaining how cookies are used on this site. By closing the notice, you will give your consent to the use of cookies, pursuant to the modalities described in this Cookie Policy. + +The site will remember your choices; therefore, the short notice will not appear if you visit other pages of the site later. In any case, you will always have the right to revoke, fully or in part, your consent. + +In case of technical issue in relation to the consent, please feel free to contact us through the form available on this site, so that we can provide you the assistance you need. + +### WHAT KIND OF COOKIES WE USE +The use of cookies by the Data Controller of this site, SparkFabrik S.r.l., with registered office in Milano (MI) Via Gustavo Fara 9, 20124, is included in the Privacy Policy of the site, available at the following [link](http://www.sparkfabrik.com). + +We use persistent cookies in order to allow the correct functioning of the site and the provision of our services (persistent cookies are stored until manual deletion by the user or until they are automatically removed); we also use the so called session cookies, which are not permanently stored on the user’s device and are deleted every time the user closes the browser. + +We use different kind of cookies – with different functionalities – which may be classified as follows: + + +**THIRD PARTY COOKIES, I.E. COOKIES INSTALLED BY DIFFERENT SUBJECTS ON PLAYBOOK.SPARKFABRIK.COM** + + +| Type of cookie | What does it do? | +|--- |--- | +| Statistics/analytics | (in order to install such cookies, it is not necessary to ask for user’s consent) These cookies are used in order to collect information on the browsing activities of the users on our site. Such information will be analysed in aggregated form, and solely for statistical purposes. Such cookies are not necessary, nevertheless they are very useful to us, and help us improve our services and contents on the basis of the information we receive from the statistics’ analysis. | + + + +### THIRD PARTY COOKIES +When browsing on this website you will receive cookies both from only from third-party websites, which may install cookies on your device on our behalf in order to deliver the services they provide. + +Third-party cookies allow us to obtain more complete surveys of user browsing habits. We use these cookies, for example, to obtain statistics on the use of our website and to evaluate your interest in specific contents or services. More detailed information on these cookies is available in this document and on the websites of the third parties installing the cookie. + +### STATISTICAL COOKIES (THIRD PARTY) + +#### GOOGLE ANALYTICS +Google Analytics is web traffic analysis service provided by Google, Inc., which provides analysis and statistics on the use of the website. + +Your browser will transmit to Google Inc. all data collected by the cookies installed by Google Analytics. Google Inc. can use such data in order to tailor ads shown to the users, on the basis of their interests. + +If you wish to disable the statistical cookies, thus preventing Google Analytics from collecting data on your navigation, you can download the special component for deactivating Google Analytics that you will find here: https://tools.google.com/dlpage/gaoptout. + +### HOW TO SET YOUR DEVICE +If you disagree with the installation of cookies on your device, you may set your browser as to disable the receipt of cookies or, in alternative, not to use this site. If you disable the cookies however, the site or parts of the site may not work properly. + +If you wish to modify the modalities of use of the cookies, to block them or to delete the cookies downloaded in your device, you can do so by changing your browser’s settings. + +Most browsers allow the user to accept or delete all cookies, or to accept only some of them (e.g. cookies from certain websites). + +The modalities to manage cookies’ preferences may change depending on the browser you are using. Further information on how to set your browser may be found at the following link: www.aboutcookies.org or by visiting the “Help” section of your browser. + +Additional information on cookies and on how to change your preferences on third party cookies can be found at the following link: www.youronlinechoices.com. diff --git a/content/guides/access-k8s-sparkfabrik-cluster.md b/content/guides/access-k8s-sparkfabrik-cluster.md new file mode 100644 index 0000000..2832e53 --- /dev/null +++ b/content/guides/access-k8s-sparkfabrik-cluster.md @@ -0,0 +1,248 @@ +## Introduction + +Since late 2016 Sparkfabrik's internal services (Gitlab, CI/CD pipelines, SparkBoard, etc) are running into a Kubernetes cluster hosted on GKE/GCP. + +This means that all intermediate environments other than local and production (so integrations, branch builds, epic builds, etc) run in pods into a Google Cloud Engine elastic cluster. The following guide will help you configure your local environment so that you will be able to access services inside pods, open shells into them, read relevant logs and - ultimately - devops all the things! :) + +## Step 1: Authentication to Google Cloud + +As said, the K8s cluster is running over Google Cloud infrastructure. To access it we first need to authenticate on GCP. +Rejoy! Your `sparkfabrik.com` account is enough to perform authentication, but you'll need to open a terminal and [install `gcloud` CLI tool](https://cloud.google.com/sdk/install). Follow the link to get `gcloud` running on your OS. + +Once done, you can authenticate running + +```text +$ gcloud auth login +``` + +Provide your `sparkfabrik.com` credentials. + +Now configure the gcloud docker integration running: + +```text +$ gcloud auth configure-docker +``` + +## Step 2: Accessing the K8s cluster + +Access to the cluster and pods therein will happen using K8s CLI tool `kubectl`. + +On MacOSX `gcloud` command has all that we need to make it work: + +```text +$ gcloud components install kubectl +``` + +While Ubuntu users can enjoy `apt`: + +```text +$ sudo apt install kubectl +``` + +Once `kubectl` is installed `gcloud` command will allow us to access the GKE cluster. +`gcloud` CLI manages so many GCP services and areas that there are commands specific to each one. To tame the complexity, all commands are grouped and subgrouped. + +Right now, the `container` group is what we need: it contains groups of commands by which we can manage GKE aspects, like clusters, node-pools, Container Registry images, and so on. + +We are going to use a command in the `clusters` subgroup of the `container` group to gain access to the cluster. That command is `get-credentials` which fetches credentials for already running clusters. + +Now, the `get-credentials` command takes a single parameter which is the **cluster name**. In our case it is `spark-op-services`. In additions there is a mandatory flag that specifies the region and the datacenter zone inside the region (namely, where is the cluster phisically running?): `--zone`. + +Last but not least, there is a global flag (not specific to the `get-credentials` command), which is `--project`. Projects in GCP are similare to realms. Not to be confused with *K8s namespaces*, (quoting GCP docs) + +> [...] projects form the basis for creating, enabling, and using all GCP services including managing APIs, enabling billing, adding and removing collaborators, and managing permissions for GCP resources. + +So let's specify the correct `spark-int-cloud-services`, that is the project that holds all the production services in Sparkfabrik. + +**Beware**: environment for customers' projects CI are not customers' assets, they are Sparkfabrik assets, payed and managed by us. That's why accessing these environments involves our production project! + +After this long explanation, the following command should be clear: + +```text +$ gcloud container clusters get-credentials spark-op-services --zone europe-west1-b --project spark-int-cloud-services +``` +A laconic message should inform you that *kubeconfig generated an entry for spark-op-services*. No frills but you can pat yourself a shoulder. You're done. + +## Step 3: Fetching info from clusters + +OK, we gained access to the cluster. Mind that's the access is read only, but you have execution permissions (namely you can run `kubectl exec`) so you can enter running pods. + +Let's test if our access is working after all. Run + +```text +$ kubectl cluster-info +``` + +and you should get a response in the lines of + +```text +Kubernetes master is running at https:// +GLBCDefaultBackend is running at https:///api/v1/namespaces/kube-system/services/default-http-backend:http/proxy +Heapster is running at https:///api/v1/namespaces/kube-system/services/heapster/proxy +KubeDNS is running at https:///api/v1/namespaces/kube-system/services/kube-dns:dns/proxy +Metrics-server is running at https:///api/v1/namespaces/kube-system/services/https:metrics-server:/proxy +``` + +If not check you followed all previous steps correctly. +Mind though that depeding on permissions on your account the output of this command may differ and you can see only a subset of the information and/or a specific error message. Keep this in mind before banging your head to the wall. + +## Step 4: Namespaces + +We mentioned projects, which is GCP realms to address accountability, ACLs and other "administrative" aspects related to the GCP services. + +Projects as never to be confused with **namespaces**. The concept of namespace here is intended as typical of Kubernetes: K8s namespaces allow to segment the same "physical" cluster in reserved spaces, like they are separate clusters. + +This makes us sure critical ops won't concur for resources or won't hinder each other in case of malfunctioning, **at a cluster level**. + +We use this feature to make sure each Gitlab project (again, not to be confused with GCP projects: we mean each customer or internal product) that needs build environments in Gitlab, lives in its own namespace. + +Let's take a look at all namespaces available in the cluster: + +```text +$ kubectl get ns +``` + +Here are a dummy response (since this is a public playbook): + +```text +NAME STATUS AGE +bunnies Active 293d +bunnies-demo Active 49d +default Active 1y +gizmo-website-d6 Active 99d +gizmo-website-d8 Active 4d +gitlab Active 345d +gitlab-test-envs-342 Active 23d +ingress-nginx Active 5d +kube-lego Active 345d +kube-public Active 1y +kube-system Active 1y +... +spark Active 345d +sparkfabrik-website-292 Active 245d +... +acme-website-304 Active 126d +acme-website-master-stage Active 36d +acme-website-subsid-stage Active 37d +acme-website-master-dev Active 121d +``` + +Some of the preceding namespaces are real. As you can see names are pretty self-explaining (at least the ones related to projects). But if you are in doubt you can check Gitlab to see which namespace is in use by a specific Gitlab projects. +Follow `Settings -> Integrations -> Kubernetes -> Namespace` in the project page to make sure (proper permissions may be necessary, ask your team leader if you can't access that section). + +## Step 5: Pods + +OK, so far we have this hierarchy: + +```text +GCP Project foo + └── Cluster bar + ├── Namespace foo-bar-alpha + ├── Namespace foo-bar-bravo + └── Namespace foo-bar-charlie +``` + +Now, each namespace can contain pods. For simplicity think of pods like *docker containers with superpowers*. + +Let's list all pods in a specific namespace, say `spark`. + +```text +$ kubectl -n spark get pod +``` +here is the result + +```text +NAME READY STATUS RESTARTS AGE +artifacts-ssh-server-7d9b9db67b-wg4hh 1/1 Running 0 5d +cron-3028794900-znhs8 1/1 Running 0 5d +dashboard-develop-499waf-849b7c95f9-4qxmr 1/1 Running 0 5d +playbook-locke-2261095262-8x8p2 1/1 Running 0 5d +``` + +This command components are: + +* `kubectl` : the client - duh +* `-n spark` : use `spark` namespace +- `get pod` : list all pods + +If we want to view the logs of a specific pod (like issuing `docker logs -f` on a normal container), try + +```text +$ kubectl -n spark logs -f +``` + +for example + +```text +$ kubectl -n spark logs -f playbook-locke-2261095262-8x8p2 + +npm info it worked if it ends with ok +npm info using npm@4.2.0 +npm info using node@v7.10.0 +npm info lifecycle locke-server@1.1.0~prestart: locke-server@1.1.0 +npm info lifecycle locke-server@1.1.0~start: locke-server@1.1.0 + +> locke-server@1.1.0 start /srv/locke +> node server.js + +Express HTTP server listening on port 80 +GET /robots.txt 404 58.932 ms - 2387 +GET /FAQ/who-to-talk-to-for 200 68.338 ms - 11073 +GET /guides/an-introduction-to-docker 200 24.580 ms +``` + +Again, let's see what the command does: + +* `kubectl` : ok, ok... +* `-n spark` : use `spark` namespace +- `logs -f` : spit logs and follow the output (like `tail -f` where `f` stands for *forever*) +- `playbook-locke-2261095262-8x8p2` : the pod name + +So, to sum things up. Since each pod can be seen as a container and each container usually runs a single service (as per best practice), with this swiss-army knife command template: + +```text +kubectl -n logs [-f] +``` + +you can see the logs of a specific service, for a specific project. +As a (almost) real life example *see apache logs for the ACME Drupal 8 website, develop environment* can translate to + +```text +kubectl -n acme-dev logs [-f] drupal +``` + +## Step 6: Accessing pods command line + +Now that we have logs we can debug 99% of the problems like a boss. Right? + +Not really... accessing the shell may be a real boon, even to make live tests and assess the problem (or a solution) quickly. + +To gain access to the shell we'll make use of the mentioned `exec` command of `kubectl` client. Let's try: + +```text +$ kubectl -n spark exec -it playbook-locke-2261095262-8x8p2 -- /bin/bash +``` + +Ta-daaan. You should be logged to the terminal as root, as simple as that. + +Dissecting the command we found: + +* `kubectl` : enough of this, right? +* `-n spark` : again, use `spark` namespace +* `exec` : this works much like in Docker +* `-it` : the same Docker flags, meaning `interactive` and `tty` +* `--` : enforces what follows as positional parameter (shell stuff actually, not partaining to kubectl) +* `/bin/bash` : the shell to be executed (see below) + +**Gotcha**: Please remind that not all containers have bash. Some (many actually) of them are based on Alpine Linux or other distros so the available shell may vary. +Alpine for example sports `ash` so you may have to issue + +```text +$ kubectl -n acme exec -it acme-ash-test -- /bin/ash +``` + +## Conclusions + +This is a small recipe to get you started with our production K8s environments. From here up it's a matter of experience, docs reading and a bit of work by you to increase your devops skills. + +Roll your sleeves and enjoy! diff --git a/content/guides/an-introduction-to-docker.md b/content/guides/an-introduction-to-docker.md index 5aabe4b..a1f64c5 100644 --- a/content/guides/an-introduction-to-docker.md +++ b/content/guides/an-introduction-to-docker.md @@ -3,7 +3,7 @@ This tutorial contains examples to become familiar with _docker_'s basics. ## Requirements Well, you must have docker up and running on your PC. -Follow the guide at [Configure local environment](/recipes/local-development-environment-configuration) if you are still out of luck. +Follow the guide at [Configure local environment](/guides/local-development-environment-configuration) if you are still out of luck. > **NOTE**: Mind that if you are on MacOSX, you must make sure that the `DOCKER_MACHINE_IP` environment variable is configured on your host system @@ -543,7 +543,7 @@ With docker-compose this is a breeze. What we basically did was: Thus all apps will have their own local infrastructure, you can start it with a single command and only when needed. The only persistent (i.e. `--restart=always`) container on the local machine is the dnsdock one. -> To learn all you need on our local environment read our [Local Environment setup guide](/recipes/local-environment-setup). +> To learn all you need on our local environment read our [Local Environment setup guide](/guides/local-development-environment-configuration). ### MacOSX Resolver's issues diff --git a/content/guides/contributing-to-tech-blog.md b/content/guides/contributing-to-tech-blog.md index 058e0fd..999f27f 100644 --- a/content/guides/contributing-to-tech-blog.md +++ b/content/guides/contributing-to-tech-blog.md @@ -124,7 +124,6 @@ Some of the lines above are very important: * `author` must match the key of your `[Params.Authors]` entry in `config.toml` (see above). In our example we used `[Params.Authors.LeanJohn]` as a key, so we kept the example consistent. * `tags` and `topics` are other metadata that currently have no effect from a user perspective. Use them at your own discretion; if in doubt spy what your mates have done in other posts and keep things consistent. - ### Add your post text Under that block, please add your markdown as you normally would with any other md-based product, **but beware** that since an `h1` is used to print the page title by Hugo, your document sections hierarchy must start from `h2`, so your first-level titles should be like: @@ -170,7 +169,7 @@ We are using the typical GitHub contribution flow, based on pull requests, so: Deploy occurs automatically on PR merge, so sit back and enjoy fame. -**NOTE**: a quick checklist is availabe at [Recipes / Tech Blog Checklist](/recipes/tech-blog-checklist) page. +**NOTE**: a quick checklist is availabe [as a procedure](/procedures/tech-blog-contributions-checklist) page. ## External contributions diff --git a/content/recipes/drupal-errors-troubleshooting.md b/content/guides/drupal-errors-troubleshooting.md similarity index 100% rename from content/recipes/drupal-errors-troubleshooting.md rename to content/guides/drupal-errors-troubleshooting.md diff --git a/content/guides/local-development-environment-configuration.md b/content/guides/local-development-environment-configuration.md index e99d87c..bb47d5d 100644 --- a/content/guides/local-development-environment-configuration.md +++ b/content/guides/local-development-environment-configuration.md @@ -5,8 +5,8 @@ Click the links to jump to the section of interest. ## Prerequisites -* Access to a Bourne-compatible shell (what's proposed here has been tested with bash) -* VirtualBox (for OS X). +* Access to a Bourne-compatible shell (all the following procedures have been tested with bash) +* VirtualBox (for OS X). If you don't have VB, yet, Docker Toolbox will install it for you. If you already have VB, you may want to choose the custom install of Docker Toolbox and deselect VB installation. ## Overview @@ -20,20 +20,22 @@ Our local development environment is build on docker, to achieve: One image is worth a thousand words, so here follows a simplified depiction of our local environment model: -![Local environment schema](%image_url%/recipes/local-development-environment--depiction-linux.png) +![Local environment schema](%image_url%/procedures/local-development-environment--depiction-linux.png) Basically, what we've got here is a set of containers, partaining to different projects. They are inerconnected via docker links so that each project has its own service: for example both Drupal projects in the image have dedicated MySQL and Apache/PHP containers, perfectly isolated. They can be stopped and started at will on a "by project" basis. -To reach each entry point, which in case of web applications is the HTTP server that exposes the app for that project, we need a resolver able to dinamically map containers to URLs when a container is started or stopped (mind a container IP is inherently dinamyc so a static map won't do). +To keep containers sets isolated we rely on `docker-compose`, a simple orchestrator that's easy to configure and run locally. -This role is carried out by a containerized service called `dnsdock`, which does exactly this. -The last ingredient consists in a local resolver able to inform the system to proxy the calls for a given TLD (`.loc` in our case) to dnsdock. This is a peculiar idiosincracy of Debian/Ubuntu whuch resolvers are managed by `network-manager` service. +To reach each entry point, that in case of web applications is the HTTP server that exposes the app for that project, we need a resolver able to dinamically map containers to URLs when a container is started or stopped (mind a container IP is inherently dynamic so a static map won't do). +This role is carried out by a containerized service called `dnsdock`, that does exactly this. + +The last ingredient consists in a local resolver able to inform the system to proxy the calls for a given TLD (`.loc` in our case) to dnsdock. This is a peculiar idiosincracy of Debian/Ubuntu which resolvers are managed dynamically by `network-manager` service (and it's better to leave it that way to avoid many headhaches). Different host OSes rely on different resolvers. -In particular MacOSX scheme is a bit different. Since MacOSX's kernel can't run native Linux containers, at the base of docker, we'll need to run Linux in it. So achieve this we'll run an Ubuntu Server instance in a VirtualBox VM, provisioned automagically with `docker-machine` a useful command of the docker suite to provision and control a remote docker host as it was local (remember the `docker` command is a CLI client). +In particular MacOSX scheme is a bit different. Since MacOSX's kernel can't run native Linux containers, we'll need to run Linux in a virtual machine. For consistency, our choice is for Ubuntu Server in VirtualBox, provisioned automagically by `docker-machine`, a useful command of the docker suite to provision and control a remote docker host as it was local (remember the `docker` command is a CLI client). -![Local environment on MacOSX](%image_url%/recipes/local-development-environment--depiction-macosx.png) +![Local environment on MacOSX](%image_url%/procedures/local-development-environment--depiction-macosx.png) On MacOSX the local host resolver is the one native to MacOSX itself, while the rest of the stack runs in a VM, where the Linux distro acts only as a containers-provider. @@ -46,91 +48,95 @@ On MacOSX the local host resolver is the one native to MacOSX itself, while the ### Automatic installation with the sparkdock privisioner (recommended way) ``` -bash <(curl -fsSL https://raw.githubusercontent.com/sparkfabrik/sparkdock/master/bin/bootstrap) +bash <(curl -fsSL https://raw.githubusercontent.com/sparkfabrik/sparkdock/master/bin/install.macosx) ``` This will provision a VirtualBox VM ready to use and will do most of the configuration required to access containers from outside the VM. Also dnsdock container will be created and activated. ### Manual Installation -Use *docker toolbox*: https://www.docker.com/toolbox +Use *docker toolbox*: https://www.docker.com/toolbox. It will install VirtualBox + Docker + Docker Tools + Docker Machine -If you already have VirtualBox, select a custom ("Ad hoc") installation and deselect VB. +If you already have VirtualBox, select a custom _ad hoc_ installation and deselect VB. -After installing Docker Toolbox, use the terminal to create *a new Docker machine* using this command: +After installing Docker Toolbox, use the terminal to create **a new Docker machine** using this command: -``` -docker-machine create dev -d virtualbox --virtualbox-disk-size 50000 --virtualbox-cpu-count 1 --virtualbox-memory 4096 +```bash +docker-machine create dinghy -d virtualbox --virtualbox-disk-size 50000 --virtualbox-cpu-count 1 --virtualbox-memory 4096 ``` Adjust the settings according to your system; the command above specify: + 1. 50GB disk size -1. 4GB ram -1. 1 CPU +2. 4GB ram +3. 1 CPU At the end of the installation use the `docker-machine ls` command, and you should see something like this: -``` +```bash % docker-machine ls NAME ACTIVE DRIVER STATE URL SWARM -dev * virtualbox Running tcp://192.168.99.100:2376 +dinghy * virtualbox Running tcp://192.168.99.100:2376 ``` -Now you should add to the init script of your shell sessions something that automatically loads environment variable needed in order to connect to the dev machine. +Now you should add to the init script of your shell sessions something that automatically loads environment variable needed in order to connect to the dinghy machine. Add this lines to your *.bashrc* or *.zshrc*: -``` -eval "$(docker-machine env dev)" -export DOCKER_MACHINE_IP=$(docker-machine ip dev) +```bash +eval "$(docker-machine env dinghy)" +export DOCKER_MACHINE_IP=$(docker-machine ip dinghy) ``` -Install *dnsdock* with this command, that will create a container that will always start once the dev machine starts: +Install *dnsdock* with this command, that will create a container that will always start once the dinghy machine starts: -``` +```bash docker run --restart=always -d -v /var/run/docker.sock:/var/run/docker.sock --name dnsdock -p 172.17.42.1:53:53/udp aacebedo/dnsdock:v1.15.0-amd64 ``` ### Check networking setup -After either manual or automatic installation, it's recommended to manually configure and test network setup: +After either manual or automatic installation, it's recommended to manually configure and test network setup. -*Set up routing* +Set up routing: -``` -sudo route -n add -net 172.17.0.0 $(docker-machine ip dev) +```bash +sudo route -n add -net 172.17.0.0 $(docker-machine ip dinghy) ``` -*Clear your DNS caches*: +Clear your DNS caches: -``` +```bash sudo killall -HUP mDNSResponder ``` Or if you are using the sparkfabrik starterkit, just run: **Drupal 7**: -``` + +```bash config/scripts/clean-dns.cache.sh ``` **Drupal 8**: -``` + +```bash docker/scripts/clean-dns.cache.sh ``` *Test* that everything is working as expected, by issuing these commands: -``` -% docker run -d -e DNSDOCK_ALIAS=test1.mysql.docker.loc -e MYSQL_ROOT_PASSWORD=root --name mysql-test sparkfabrik/docker-mysql -% ping test1.mysql.docker.loc +```bash +% docker run -d -e DNSDOCK_ALIAS=test1.redis.docker.loc --name redis-test redis:alpine +% ping test1.redis.docker.loc -PING test1.mysql.docker.loc (172.17.42.37): 56 data bytes +PING test1.redis.docker.loc (172.17.42.37): 56 data bytes 64 bytes from 172.17.42.37: icmp_seq=0 ttl=63 time=0.275 ms -% docker rm -vf mysql-test +% docker rm -vf redis-test ``` These commands: + * create a temporary container that will instantiate a MySQL server * ping the newly created service, using the predefined hostname, managed through dnsdock * remove the temporary container (and service) and clean up the space occupied by the container @@ -145,8 +151,8 @@ These commands: It my be late to state this but **avoid to encrypt your home directory**! It will gives at least two major disservice: -# Build operations on Drupal sites will have a **relevant** drop in performance -# Crypted FS in Ubuntu won't support filenames longer than 143 chars. We rely on **at least** a community contributed patch which name sums up to 144 chars. +1. Build operations on Drupal sites will have a **relevant** drop in performance +1. Crypted FS in Ubuntu won't support filenames longer than 143 chars. We rely on **at least** a community contributed patch which name sums up to 144 chars. ### Overview @@ -164,13 +170,13 @@ To have a functional environment on a Linux machine we will: In order to install Docker, follow the *official documentation* at Docker's website. Instructions are available for all famous distros. -"Here the documentation":https://docs.docker.com/installation/ubuntulinux for Ubuntu users. +[Here the documentation](https://docs.docker.com/installation/ubuntulinux) for Ubuntu users. -*IMPORTANT*: Make sure you also "follow the instructions":https://docs.docker.com/installation/ubuntulinux/#optional-configurations-for-docker-on-ubuntu at the chapter "Create a Docker group". +> **IMPORTANT**: Make sure you also [follow the instructions](https://docs.docker.com/installation/ubuntulinux/#optional-configurations-for-docker-on-ubuntu) at the chapter "Create a Docker group". -*HINT*: On Ubuntu the official `docker-engine` package you just installed creates the `docker` group for you. You must ensure your user belongs to that group. You can do it with: +> **HINT**: On Ubuntu the official `docker-engine` package you just installed creates the `docker` group for you. You must ensure your user belongs to that group. You can do it with: -``` +```bash sudo usermod -aG docker ``` @@ -179,10 +185,10 @@ sudo usermod -aG docker Docker compose is a binary command which is not packaged for each individual OS/distro. Installing it is as easy as downloading the last binary in a shared executable path. Issue those command *as root* on Ubuntu, no matter the version of OS you are running. -> Important: run as root, like with `sudo su` +> **IMPORTANT**: since you need a superuser complete environment, run the following commands as root, like with `sudo su` -``` -export COMPOSE_VERSION_NUMBER=1.7.0 && \ +```bash +export COMPOSE_VERSION_NUMBER=1.23.1 && \ curl -L https://github.com/docker/compose/releases/download/$COMPOSE_VERSION_NUMBER/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose && \ chmod +x /usr/local/bin/docker-compose ``` @@ -192,11 +198,11 @@ chmod +x /usr/local/bin/docker-compose dnsdock is a service which is automatically instructed by the docker engine every time a container is started with the option `-e DNSDOCK_ALIAS=`. Being it a Linux service we can leverage docker to install and start it without messing around with packages or such (nice uh?). -*HINT:* Make sure your user has been added to the docker group. +> **HINT**: Make sure your user has been added to the docker group. Run the container that will host dnsdock service -``` +```bash docker run --restart=always -d -v /var/run/docker.sock:/var/run/docker.sock --name dnsdock -p 172.17.0.1:53:53/udp aacebedo/dnsdock:v1.15.0-amd64 ``` @@ -211,15 +217,46 @@ Issuing this command, docker will: If you run into trouble due to port 53 being bound on the network, don't warry and read along. -### Installing / Configuring dnsmasq +### Configuring systemd-resolved (Current - Ubuntu 18.04 LTS +) + +> **NOTE**: Ubuntu 18.04 LTS is the current recommended version. for which the following is not necessary. Should you need to configure a legacy version of Ubuntu (14.04 to 16.04 LTS), [jump to the correct paragraph](#installing--configuring-dnsmasq-legacy---ubuntu-1404-to-1604-lts). + +With the migration to `systemd`, Ubuntu 18.04 adopted the `systemd-resolved` service. This is a sort of catchall, multiprotocol name-resolving system that also provides a stub for DNS resolutions for local traffic. + +The piece basically sits where `dnsmasq` used to in former OS versions. Sadly `resolved` configuration is nowhere as clean and powerful as `dnsmasq`, leading to two minor problems. + +1. We have to change a system configuration file to make it work. This becomes a problem if you want to upgrade to the next LTS since the procedure will complain about the changed file (not a big problem but still). +2. The service happens to head in a sort of race condition when new containers are spawn from time to time, so resolve new containerized service can stop working (we have [a simple workaround](#workaround-for-resolveddnsdock-lock-up) for this). + +The good news is that the procedure is simpler than `dnsmasq` configuration. Just edit `/etc/systemd/resolved.conf` as superuser and add the following lines to the end of the file: -This part of the guide has been tested to work on Ubuntu from LTS version 14.04, up to 16.04+ LTS. So far the recommanded version is 16.04.1 LTS. +```text +DNS=172.17.0.1 +Domains=~loc +``` + +> **NOTE**: both `DNS` and `Domains` config options are commented in the standard `resolved.conf` file, but both are present. You can uncomment them of course. We advice you to put new lines at the end since it will be simpler to compare changes during an LTS upgrade. The important thing is that you **make sure you don't have conflicting configurations from a previous customization**. + +#### Workaround for resolved/dnsdock lock-up + +As mentioned above, `resolved` and `dnsdock` may end up in a deadlock. The effect is that your OS won't be able to resolve new containers started with `docker-compose`. Restarting the services will suffice to make things work again: + +```bash +docker restart dnsdock && sudo service systemd-resolved restart +``` + +Too bad this requires to provide superuser password. +You can alias this command to something mnemonic (say `bazooka`) so that fixing things will be easy. You won't regret having this alias. + +### Installing / Configuring dnsmasq (Legacy - Ubuntu 14.04 to 16.04 LTS) + +> **NOTE**: This part of the guide works on Ubuntu from LTS version 14.04, up to 16.04+ LTS. The current recommended version is 18.04 LTS, for which the following is not necessary. To properly configure 18.04 LTS, [jump to the correct paragraph](#configuring-systemd-resolved-current---ubuntu-1804-lts-). Ubuntu 14.04 to 15.10 natively relies on `dnsmasq` a great and simple dns-proxy which allows for very elastic configuration of the networking stack. Most of all, `dnsmasq` plays very well with `resolvconf`, a very dull daemon which controls local resolution maps to make sure dynamically created networks never run into conflicts with each other. Ubuntu 16.04 ships with a default dnsmasq configuration in the `/etc` folder, but the service itself is not installed by default. If you are on this OS version or if for some other reason you don't have dnsmasq installed, go forth and install it right away (don't worry, it's completely preconfigured to work transparently on a stock Ubuntu). -``` +```bash sudo apt-get install dnsmasq ``` @@ -235,7 +272,7 @@ Since we don't want our configuration to be replaced in case we upgrade the syst Put what follows in that file: -``` +```text server=/loc/172.17.0.1 bind-interfaces except-interface=docker0 @@ -247,7 +284,7 @@ The first line tells dnsmasq to proxy all queries for `.loc` domains to dnsdock, Restart dnsmasq -``` +```bash sudo service dnsmasq restart ``` @@ -255,14 +292,14 @@ And you're done. *HINT*: if you followed provious steps and had dnsmasq already running, you may have to kill and restart your dnsdock to make it bind to the now available port 53 on `docker0` interface: -``` +```bash docker kill dnsdock && \ docker run --restart=always -d -v /var/run/docker.sock:/var/run/docker.sock --name dnsdock -p 172.17.0.1:53:53/udp aacebedo/dnsdock:v1.15.0-amd64 ``` -*HINT*: if you have a local stack installed for other reasons and need to resolv a subset of `.loc` domains to localhost you can change the above configuration this way +> **HINT**: if you have a local stack installed for other reasons and need to resolv a subset of `.loc` domains to localhost you can change the above configuration this way -``` +```text address=/loc/127.0.0.1 server=/sparkfabrik.loc/172.17.0.1 except-interface=docker0 @@ -278,38 +315,20 @@ To test everything is working as expected, we'll try to run a service in a conta > Do NOT execute as root, use your user to run containers -``` +```bash docker run -d -e DNSDOCK_ALIAS=testing.docker.with.mysql.sparkfabrik.loc -e MYSQL_ROOT_PASSWORD=root --name mysql-test sparkfabrik/docker-mysql && \ ping testing.docker.with.mysql.sparkfabrik.loc ``` You should see you can ping the running container smoothly (something in the lines of) -``` +```bash PING testing.docker.with.mysql.sparkfabrik.loc (172.17.0.37): 56 data bytes 64 bytes from 172.17.42.37: icmp_seq=0 ttl=63 time=0.275 ms ``` If all works, clean the test container and remove its image with -``` +```bash docker rm -vf mysql-test ``` - -## Arch Linux (dns configuration) - -Instructions are basically the same of Ubuntu Linux: - -* Install dnsmasq -* Create the `/etc/dnsmasq.d/dnsdock-resolver` file -* Start dnsmasq `systemctl start dnsmasq.service` -* Check dnsmasq status: `journalctl -u dnsmasq` - -Then, if you have the `'port 53 problem'`, proceed as above: - -* Add `nameserver 172.17.0.1` to `/ect/resolv.conf` -* Uncomment `port=5353` into `/etc/dnsmasq.conf` file -* Restart dnsmasq `systemctl restart dnsmasq.service` -* Restart dnsdock container -* Enjoy :) - diff --git a/content/guides/setup-openvpn-with-ubuntu-networkmanager.md b/content/guides/setup-openvpn-with-ubuntu-networkmanager.md new file mode 100644 index 0000000..b822091 --- /dev/null +++ b/content/guides/setup-openvpn-with-ubuntu-networkmanager.md @@ -0,0 +1,51 @@ +/* +Title: Setup OpenVPN with Ubuntu NetworkManager +*/ + +Setting up OpenVPN on NetworkManager on Ubuntu can be a PITA, but not if you follow these steps! + +## Prerequisite + +* Ubuntu 18.04+ or 16.04 (preferrably with Gnome Desktop Manager) +* OpenVPN 2.4+ + +Ubuntu 16.04 ships OpenVPN 2.3+, it's quite easy to upgrade it: + +``` +sudo curl -s https://swupdate.openvpn.net/repos/repo-public.gpg | sudo apt-key add +echo "deb http://build.openvpn.net/debian/openvpn/stable xenial main" > /etc/apt/sources.list.d/openvpn-aptrepo.list +sudo apt update +sudo apt install -y openvpn +``` + +## Step-by-step + +First of all install the NetworkManager OpenVPN extension. + +```bash +sudo apt install network-manager-openvpn-gnome +``` + +Then create a new network using NetworkManager's settings. + +On the type of network selection screen, select `VPN`. + +![NM Select network](%image_url%/procedures/nm-select.png) + +Then `Import from file...`. + +![NM Select ovpn](%image_url%/procedures/nm-openvpn-select.png) + +And select the file that `support@sparkfabrik.com` sent you. The file name should be similar to: + +`firewall-UDP4-1194-edoardo.dusi-config.ovpn` + +> **IMPORTANT FINAL PART** + +When you review the settings that NM imported, enter the username and password given to you by `support` and then check the option `Store the password for all users` on the password's options. + +![NM All Users](%image_url%/procedures/nm-allusers.png) + +## There you go + +![NM Connected](%image_url%/procedures/nm-vpn-connected.png) diff --git a/content/guides/sort b/content/guides/sort index 64bb6b7..425151f 100644 --- a/content/guides/sort +++ b/content/guides/sort @@ -1 +1 @@ -30 +40 diff --git a/content/index.md b/content/index.md new file mode 100644 index 0000000..843bd24 --- /dev/null +++ b/content/index.md @@ -0,0 +1,41 @@ +/* +title: SparkFabrik playbook +*/ + +What you are reading is the _manual_ of our company. +As every organization we have rules, policies, practices, processes and procedures and these pages are primarly meant as a clear reference for our workforce, so that nobody gets lost during everyday work. + +But at the same time, this is our effort to be transparent, clear and fair to anyone so that the way we work may be followed, discussed and evolved even by people outside the organization. + +Many useful information can be found here about how SparkFabrik works and we also value contributions and feedback, so don't be shy. + +## Playbook sections + +This playbook is organized into the following sections: + +* **Organization**: how we are structured, which functional roles are recognized in the company, their responsibilities and company's expectations. +* **Working at SparkFabrik**: how we hire, pay, evaluate, reward and listen to our workforce. +* **Tools and policies**: pretty much as it sounds, learn here about our rules and what the company provides to follow them. +* **Procedures**: best practices for specific tasks; our procedures evolve and adapt over time but at any moment, you can find them here. +* **Guides**: how to do things the best way; guides differ from procedures in that they are descriptive, not prescriptive. +* **Resources**: find here those important things you may need every now and then. +* **FAQ**: very helpful to newcomers, but also to veterans that want to refresh their minds. + +## Credits + +This playbook and many company practices have been heavily inspired by [Deeson](https://www.deeson.co.uk/), so many thanks go to that nice guy. + +Our practices owe a great tribute to the guys at [StackOverflow](https://stackoverflow.com/). + +We learned to value transparency as a propeller to innovation dwelling in [Agile](https://agilemanifesto.org/) and [FOSS](https://www.fsf.org/) culture. + +This Playbook is powered by a small and effective piece of free software called [Raneto](http://raneto.com/), one of the best choice for minimum effort knowledgebase keeping. + +## Feedback and contributions + +You can find the source of these pages on [GitHub](https://github.com/sparkfabrik/company-playbook). +You can file issues, fork the project and send PRs. + +## License + +Creative Commons License
SparkFabrik Playbook by Sparkfabrik Srl is distributed under Creative Commons Attribution - Sharealike 4.0 International license. \ No newline at end of file diff --git a/content/organization/administration.md b/content/organization/administration.md new file mode 100644 index 0000000..69781fe --- /dev/null +++ b/content/organization/administration.md @@ -0,0 +1,15 @@ +/* +Description: Administration roles and functions in SparkFabrik +Sort: 15 +*/ + +## Administration owners + +Administration in Sparkfabrik is carried out mainly by members of the [Executive Board](/organization/governance) with the help of [Supporters](/organization/role-isc-supporter) - employees owning one or more processes and procedures vital to the health of the company. + +Despite not being directly involved in core-business or value delivery, Supporters are **the glue that holds governance and operations together**, thus being an essential gear in the company machinery. +They are facilitators, assistants, secretaries, organizers and the ultimate source of truth about so many information necessary to managers to properly hold the steering wheel. + +The [Supporter role](/organization/role-isc-supporter) has its own [impact scoring card](/working-at-sparkfabrik/impact-scoring) and, if not for the nature of its duties, is subject to the same requirements and quality standards as the other [operational roles](/organization/operations). + +In addition to supporters, [Lead developers](/organization/role-isc-lead-developer) and [Professionals](/organization/role-isc-professional) are often involved in administrative processes like reporting, project budgeting, lead assessment and so on. \ No newline at end of file diff --git a/content/organization/governance.md b/content/organization/governance.md new file mode 100644 index 0000000..7675a0a --- /dev/null +++ b/content/organization/governance.md @@ -0,0 +1,53 @@ +/* +Description: Governance roles and functions in SparkFabrik +Sort: 20 +*/ + +Governance in Sparkfabrik is organized in functions, not roles. +C-level roles are assigned to key people, that generally own government functions. Owning doesn't imply the function is totally carried out by that person. Professionals and lead developers at operational level cooperate with the government function owner to make it happen. + +## Executive board + +The executive board is in charge for the strategy and business planning of the company. +Current board is composed by company founders, with the following duties. + +* **Stefano Mainardi**: CEO - Responsible for the overall progress of the company. Praised for success, and held responsible for setback. +* **Paolo Pustorino**: Head of HR - Responsible for workforce training, development, management, recruitment, rewarding, compliance and ethos. +* **Marco Giacomassi**: CFO - Oversees company's financials. Responsible for budgeting, accounting, reporting, forecasting and investing. +* **Paolo Mainardi**: CTO - Oversees company's technology. Works to ensure that technology-related decisions align with business goals. +* **Alessio Piazza**: COO - Oversees company's day-to-day operations, sourcing, process control, resource allocation and activity planning. + +## Steering committee + +The steering committee works to overcome organizational problems and advance company's practices. It operate on a constant basis on top of the projects level, overseeing the processes, validating methodologies and improving the whole delivery process. + +This committee is composed by the CTO, COO, Head of HR, all Professionals and all Lead Developers in the company. +The owner of Steering committee events is the COO. + +Each quarter (the first Wednesday of each quarter first month) the committee has a 2 hours facilitated meeting in which they define: + +* Top priorities to be addressed (C-levels can set them or call for co-generation and voting) +* State top priorities in terms of initatives +* Willing people can apply as owners of those initiatives + +Initiatives clearly states SMART goals to address the related top priority. They should bring a change or even revolutionize an aspect of our work, such as introducing a new technology, change an organizational approach, introducing longed-for tools, etc. + +Owners commit to lead the completion of the initiative goals by the end of the quarter. Initiative owners will be pubblicly appointed. We want those people to challenge themselves and take on additional responsibilities to shape those skills that may in the future make them C-levels. + +The format of the quarterly meeting is aggressively timeboxed: + +* 20 mins: Identify and list weaknesses or opportunities for improvement in current approach. +* 30 mins: Define goals for a better condition (1 to 3 goals depending on the size). +* 30 mins: Generate SMART initiatives for the quarter that fulfills the goals. +* 20 mins: Appoint a single owner for each initiative. +* 10 mins: Define a scheduled session within 7 days where the owner will present and discuss his incremental plan to the completion of the goals (this will allow resource planning and assignement). + +The presentation of the initiative plan must include: + +* Quantification/qualification of time and resources necessary to fulfill the goal. +* A list of the deliverables to be expected (tools, docs, materials, etc). +* A calendar for brown bags/internal presentation to review increments with the whole company. +* If and how the company is expected to support the initiative deliverables, during the quarter and in the future (say, open source contributions etc). +* A list of outward facing material to communicate how your initiative is making a difference, such as blog posts, events speeches or the maintenance of open source contributions. + +While the initiative should be completed in the quarter, the ownership won't stop there: communication, promotion and ongoing maintenance may last longer and owners are supposed to take the commitment. diff --git a/content/organization/operations.md b/content/organization/operations.md new file mode 100644 index 0000000..dcdd10e --- /dev/null +++ b/content/organization/operations.md @@ -0,0 +1,35 @@ +/* +Description: Operational roles and functions in SparkFabrik +Sort: 10 +*/ + +In Sparkfabrik the term _developer_ is used generally to identify employees that deliver solutions to the customer. +It doesn't really matter if your job is to write code, design a new interface or taking care of the operations on a cloud appliance. Your job is still to _develop_ things: be it from scratch or to improve them. + +## Careers + +Operationals career paths expand vertically (_Growth_) and horizontally (_Specialities_). + +### Growth + +We recognize four levels of professional skills, depending on seniority and level of proficiency. Each level has its own salary bracket, mission and clear expectations. Developers [progress over this career path](/working-at-sparkfabrik/career-advancement.md) by their lenght of service, their results and by nurturing their technical and non-technical skills. + +* **Junior developer**: this is the level where duly graduated people or developers already experienced on other technologies start. We expect people to quickly step up to the next level, ideally in 12 to 36 months of employment. +* **Senior developer**: this is the level that compose the big part of our company and that we heavily rely upon. People at this level are skilled and proficient with both our technology and our methodology. They can mentor juniors and are authonomous in their work. +* **Lead developer**: those are the people that lead teams and projects in Sparkfabrik. Those people have a senior level background on top of which they developed the soft skills necessary to govern the social, technical and organizative complexity of our work. +* **Professional**: this is the highest operational role in Sparkfabrik. Professionals are the people that embody a speciality, can work with one or multiple teams at once, represent Sparkfabrik at important tables, provide training and mentorships, etc. Professionals may occasionally lead a team, but they are actually supposed to work cross-teams as reference key people. + +Learn more about each [role accountabilities](/organization/roles-accountabilities). + +### Specialities + +We explained Sparkfabrik only employs _developers_. Sure there are differences and each person has her own natural or acquired inclination. We broadly recognize four _Specialities_ that qualifies you as a developer and do our best to make you shine in accordance with your nature. During your career you will be probably cover more than a single speciality, even at the same time. + +* **Analyst**: Analysts are great when it comes to map a domain, fathom complexity and express it in a clear, rational, understandable form. Analysts may not always have a solution at hand but for sure they know when a need is fulfilled or a problem is solved. Analysts skills make for great Product Owners. +* **Architect**: Architects describe the best possible solution to a framed problem. They are great decision makers, understand the long term implications of technical choices, know how to quickly probe, understand and adapt and always grasp the big picture. +* **Specialist**: Specialists are vertically expert in a discipline or area, be it writing software, cloud operations, implementing Agile or UX design. Those are the most keen to work in pair with project teams on the long run, when there are critical challenges. +* **Manager**: Managers make things work. They coach, measure, plan, steer and ultimately support people to give their best, remove obstacles, improve their processes and procedures. In Sparkfabrik people are never managed, work is. So managers govern but never rule. + +## How to advance + +We track and rule [people career advancement](/working-at-sparkfabrik/career-advancement.md) to make it fair and clear to everybody. diff --git a/content/organization/roles-accountabilities.md b/content/organization/roles-accountabilities.md new file mode 100644 index 0000000..d27d0f5 --- /dev/null +++ b/content/organization/roles-accountabilities.md @@ -0,0 +1,43 @@ +/* +Title: Roles accountabilities +Description: Accountabilities and Scoring Cards for the different roles in Sparkfabrik +Sort: 40 +*/ + +## Shared accountabilites + +We all share a set of accountabilities, regardless of our job position and role on any specific project: + +### Client satisfaction + +Client is not always right, or they would not turn to us to solve their problems. Still [we value technical quality and good human relations over aything else](https://www.sparkfabrik.com/en/who-we-are.html). Be kind and clear, explain your positions, always focus on customer needs, with open ears and a bright smile. Everybody is called to ultimately deliver a great customer experience. + +### Delivering projects + +Simple as it sounds. On time, on budget, on specs. + +### Respecting you colleagues + +Be friendly. Keep in mind that we share the same goal but everybody may have different way to achieve it. Always presume everybody il well-meaning and help her to improve. Don't waste others time: be timely at meetings, point out when other forget something and state your requirements or needs in a clear way so other should not try to figure out what you mean. + +### Supporting your colleagues + +Work with others so that they can grow. Add to their knowledge. Help them if they are in the need but don't steal the spotlight: let them do the work so they can improve. Point out when other can meet a highest standard. Don't hold information that can help other succeed. + +### Following company processes + +We prefer processes and evolutionary agreements over rules. Still we want everybody to follow those processes and respect evolutionary agreements. Everybody is involved in shaping them so everybody must respect them. + +## Per-role accountabilities + +Operational roles are described in terms of **impact scoring cards**: documents that describe the expected positive impact a role has to the business. + +As you take on new roles and possibly even move between specialities (we love multi-talented people), your specific accountabilities will be described by one (or more) scoring cards. + +* [Junior developer](/resources/role-isc-junior-developer) +* [Senior developer](/resources/role-isc-senior-developer) +* [Lead developer](/resources/role-isc-lead-developer) +* [Professional](/resources/role-isc-professional) +* [Supporter](/resources/role-isc-supporter) + +Find [printable version of all ISCs](https://docs.google.com/document/d/1U_aoVG1i1KkP7u-JvzBdoExGK_R6iZgTo0E6Ylm1alU/edit?usp=sharing) in this document. It's a single file, so mind to print only the pages you need. diff --git a/content/organization/sort b/content/organization/sort new file mode 100644 index 0000000..c227083 --- /dev/null +++ b/content/organization/sort @@ -0,0 +1 @@ +0 \ No newline at end of file diff --git a/content/our-company/roles-in-sparkfabrik.md b/content/our-company/roles-in-sparkfabrik.md deleted file mode 100644 index 10161d9..0000000 --- a/content/our-company/roles-in-sparkfabrik.md +++ /dev/null @@ -1,20 +0,0 @@ -In SparkFabrik we make distinction between **Company Roles** and **Team roles**. - -We don't have such a thing like **Job roles** since we are currently all developers, each one with its skill-level and focus, but pretty all devoted to create digital products. This basically means we won't hire for a _Project manager_. We probably will search for a more or less skilled technician and he will eventually end up doing what he does best. - -The main difference between **Company roles** and **Team roles** is that the latter are generally interchangeable, while the formers tend to be fixed and company-wide. All Company roles are currently covered by company shareholders and founders. - -## Company roles - -* **CEO** - Stefano Mainardi (stefano.mainardi@sparkfabrik.com) and Paolo Pustorino (paolo.pustorino@sparkfabrik.com) are currently CEOs of the company, with equal powers. -* **CTO** - Paolo Mainardi (paolo.mainardi@sparkfabrik.com) is the current CTO of the company -* **CFO** - Marco Giacomassi (marco.giacomassi@sparkfabrik.com) is the current CFO of the company -* **Software Architect** - Alessio Piazza (alessio.piazza@sparkfabrik.com) is the current Software Architect of the company -* **Office Manager & Administrative Officer** - Ayse Meric (ayse.meric@sparkfabrik.com) is the current Office Manager & Administrative officer - -## Team roles diff --git a/content/our-company/sort b/content/our-company/sort deleted file mode 100644 index 573541a..0000000 --- a/content/our-company/sort +++ /dev/null @@ -1 +0,0 @@ -0 diff --git a/content/procedures/drupal-8-development-workflow.md b/content/procedures/drupal-8-development-workflow.md new file mode 100644 index 0000000..739aa20 --- /dev/null +++ b/content/procedures/drupal-8-development-workflow.md @@ -0,0 +1,27 @@ + +## Prerequisite + +When you start working, commit your local changes and merge the integration branch `git commit -m '..' . && git pull` + +## In pills + +* Export your drupal configuration into sync directory: `drush config-export sync` +* Commit your drupal configuration +* Pull or merge integration branch to get other devs changes +* Resolve merge conflicts +* Import the resulting configuration into your drupal installation: `drush config-import sync` +* Check that after the import everything in working as expected (better running tests) +* Export again your configuration: `drush config-export sync` (credits to Nuvole for this suggestion) +* **OPTIONAL** Squash if submitting a MR +* Push your changes +* **OPTIONAL** create a MR on gitlab +* live happily forever after :) + + +## Slides by Nuvole + +Find a backup copy of Nuvole's slides on our [Google Drive](https://drive.google.com/open?id=0B3bEkSMDrX8YRzBrWkxkZ3FxQkk5UEJNMnktZS11UDZjc0hN). + +### Excerpt from this presentation: + +![Slides by nuvole](%image_url%/procedures/drupal-8-development-workflow.png) diff --git a/content/procedures/employee-onboarding.md b/content/procedures/employee-onboarding.md new file mode 100644 index 0000000..5b44bf3 --- /dev/null +++ b/content/procedures/employee-onboarding.md @@ -0,0 +1,91 @@ +This is a checklist and flight-plan for new employees onboarding. + +The document provides both _procedural_ tasks (such as opening accounts) and a depiction of the processes and assets that can help the decision making phase of an onboarding: assigning the employee to a team, mentoring her, setting goals and evaluate results. + +## Requirements + +The following steps give access to all confidential information in the company, so before proceeding, check that: + +1. The person hiring legally started (from the present day) **OR** +2. There is a _non disclosure agreement_ running between the parties + +## Devices, tools and objects + +* A laptop PC must be ordered **in advance** so that it will be available on the first day of work +* For resident employees, coming to the office on a daily basis, a the office keys must be provided ideally from the first day +* Named business cards will usually be ordered after the end of the contractual trial period +* We usually provide a branded backpack with the laptop and branded stickers for the screen lid + +## Pre-flight checks + +An HR or Admin representative will perform the following actions: + +* Open a `@sparkfabrik.com` account +* Add the newly created account to `staff@sparkfabrik.com` group +* Add the newly created account to all relevant `*-team@sparkfabrik.com` project/team mail groups +* Add the account to company's OpenVPN firewall (for external access) +* Open the Gitlab account and add it to all relevant projects +* Open the Toggl account and make sure it can access all relevant projects +* Add the account to Slack and _invite_ it on `#general` and `#tech` as well as on all channels related to relevant projects + +## Things to do on the first day + +### For the company + +* HR must introduce the new employee to the resident team and, on slack `#general` channel, to the remote colleagues +* HR must assign a buddy (usually her team leader) to the new employee +* Tech must make sure the local development environment is working on the employee's PC +* HR must send an introductory e-mail with policies (links) about + * Resource access + * Time tracking + * Management of off/sick days + * Google Drive folder structure and usage + * Google Calender configuration and conventions + * How and whom to ask for help + * 1:1 meetings and performance review policies (ISCs) +* HR must meet with the employee to make sure she got the policies and she can correctly understand them in context +* Tech should send in introductory e-mail with information (links) about + * Relevant starting training resources (accounts on _drupalize.me_ or _Udemy_, books or playbook pages) + * How to contribute to the projects (branching model, peer review, etc) + * Required tools, procedures and practices one need to know from the very beginning +* Tech and/or buddy must explain our key internal projects and self-made tools (sparkdrupal, sparkangular, sparkboard, firestarter, etc) to the employee + +### For the employee + +What follows will be performed with the help of your buddy, if needed + +* Access all the services and check you can interact with them +* Activate two-factor auth on Gitlab +* Add SSH keys on Gitlab so you can clone the repositories +* Set your profile pictures (starting with Gravatar and checking on Gitlab, Slack, Toggl, etc) with an appropriate/decent close-up (or use the [facewall shot](#facewall-shot)) +* Set your e-mail signature in [the format](#Standard-mail-signature-format) below (respect bolds) + +## Things to do within the first week + +* HR and the employee will schedule a brief talk where the employee will self-introduce to the company +* HR will arrange a shooting session for the website facewall (this can also be used as a profile picture) + +## Things to do one month after the onboarding + +* HR will survey the employee to collect feedback about the onboarding process +* HR will arrange a meeting between the whole management and the employee to share general evaluations and conclude the onboarding phase + +## Snippets + +### Standard mail signature format + +> **SPARKFABRIK** +> +> **Name Surname** +> Role or function +> +> +39 XXX XX.XX.XXX +> https://www.sparkfabrik.com + +Role or function can be: + +* Software Developer +* Lead developer +* C-Level or other management board function + +When in doubt, ask a HR representative. diff --git a/content/recipes/git-rebase-workflow.md b/content/procedures/git-rebase-workflow.md similarity index 100% rename from content/recipes/git-rebase-workflow.md rename to content/procedures/git-rebase-workflow.md diff --git a/content/recipes/kickstart-a-new-project.md b/content/procedures/kickstart-a-new-project.md similarity index 100% rename from content/recipes/kickstart-a-new-project.md rename to content/procedures/kickstart-a-new-project.md diff --git a/content/procedures/projects-environments-availability.md b/content/procedures/projects-environments-availability.md new file mode 100644 index 0000000..c46d6ba --- /dev/null +++ b/content/procedures/projects-environments-availability.md @@ -0,0 +1,33 @@ +## Projects environments general availability + +Our CI pipelines build a lot of different environments for each project every day. +Aside from branch-related pipelines built for automated testing purposes, we also have more stable environments like staging, demos or develop. + +Those environments live on a Kubernetes cluster (see [Access Kubernetes Sparkfabrik cluster](/guides/access-k8s-sparkfabrik-cluster)) which under load may scale well over 20 active nodes. To reduce costs **and** to enforce our policies on a healthy work/life balance, we leverage the dynamic nature of the cloud and scale the cluster down to 2 or 3 nodes after 8:00PM. At 8:00AM the environment are respawn transparently. +Same happens during the weekends, so you're not supposed to visit a staging environment on sunday. We really hope you have something better to do! + +So, **if you try to connect to an environment during the _down phase_** and you get something like a _503 Bad gateway_ error, don't fire the alarm! As long as nobody of the operations team communicated scheduled or unscheduled maintenance activities, you environments will be up and running normally the next day. + +## Special needs + +Of course, your project may need a different treatement. + +### I need my project to stay up at night/during the weekend on a permanent basis + +OK, no problem. Reach out for the operations team or write to [support@sparkfabrik.com](mailto:support@sparkfabrik.com) and we'll set it up according to the necessity. + +### I have a demo/event/whatever during the weekend for a single time and I really need a specific project environment to be up and running + +Again, get in touch with the operations team or write to to [support@sparkfabrik.com](mailto:support@sparkfabrik.com) but please **plan the event in advance** so that the team won't have to rush and the risk of errors is reduced. + +### I occasionally need to work on the environment outside normal working hours + +You can reprovision a shutdown environment by yourself. Just run the last deploy job in the project for the necessary environment. You don't need to re-run the whole build pipeline, just the deploy job. This will make the environment up and running up to the next working day. + +## Urgent support + +If none of the above work and something really bad is about to happen, reach out on Slack, phone or mail for: + +* Paolo Mainardi +* Alessio Piazza +* Marco Giacomassi \ No newline at end of file diff --git a/content/procedures/sort b/content/procedures/sort new file mode 100644 index 0000000..64bb6b7 --- /dev/null +++ b/content/procedures/sort @@ -0,0 +1 @@ +30 diff --git a/content/recipes/tech-blog-checklist.md b/content/procedures/tech-blog-contributions-checklist.md similarity index 100% rename from content/recipes/tech-blog-checklist.md rename to content/procedures/tech-blog-contributions-checklist.md diff --git a/content/recipes/drupal-8-development-workflow.md b/content/recipes/drupal-8-development-workflow.md deleted file mode 100644 index a058b03..0000000 --- a/content/recipes/drupal-8-development-workflow.md +++ /dev/null @@ -1,30 +0,0 @@ - -## Prerequisite - -When you start working, commit your local changes and merge the integration branch (git commit -m '..' . && git pull) - - -## In pills - -[] are optional. - -* export your drupal configuration into sync directory (drush config-export sync) -* commit your drupal configuration -* pull or merge integration branch to get other devs changes -* resolve merge conflicts -* import the resulting configuration into your drupal installation (drush config-import sync) -* check that after the import everything in working as expected (better running tests) -* exort agiain your configuration (drush config-export sync) [this was suggested by Nuvole] -* [squash if submitting a MR] -* push your changes -* [create a MR on gitlab] -* be happy :) - - -## Slides by Nuvole - -https://drive.google.com/open?id=0B3bEkSMDrX8YRzBrWkxkZ3FxQkk5UEJNMnktZS11UDZjc0hN - -### Excerpt from this presentation: - -![Slides by nuvole](%image_url%/recipes/drupal-8-development-workflow.png) diff --git a/content/recipes/sort b/content/recipes/sort deleted file mode 100644 index 425151f..0000000 --- a/content/recipes/sort +++ /dev/null @@ -1 +0,0 @@ -40 diff --git a/content/our-company/company-manifesto.md b/content/resources/company-manifesto.md similarity index 74% rename from content/our-company/company-manifesto.md rename to content/resources/company-manifesto.md index cadad1f..1a06644 100644 --- a/content/our-company/company-manifesto.md +++ b/content/resources/company-manifesto.md @@ -1,4 +1,9 @@ -We require all our employees and contributors to endorse our [Company Manifesto](http://www.sparkfabrik.com/manifesto.html). +/* +Description: Which values underpin SparkFabrik's culture +Sort: 10 +*/ + +We require all our employees and contributors to endorse our [Company Manifesto](http://www.sparkfabrik.com/en/manifesto.html). Sharing our values is a great indicator you can work with us, so please, take a look at them before apply for hiring. The Manifesto is a living document, so it is bound to change, moving along with our collective values. This won't happen frequently but will do from time to time. diff --git a/content/resources/promotional-resources.md b/content/resources/promotional-resources.md new file mode 100644 index 0000000..f97905d --- /dev/null +++ b/content/resources/promotional-resources.md @@ -0,0 +1,18 @@ +/* +Sort: 20 +*/ + +This page lists a set of official resources that anyone in SparkFabrik may use for communication and promotion. + +Those assets must be preferred to any other variant, so always make use of these templates and media, unless you have a very good reason not to. + +## Presentation templates + +Since we have different OSes on our company's hardware, we rely on Google Suite for company documents editing. +When you need to create a new presentation, refrain to use local/proprietary solutions and stick with what we chosed. + +For slides sets, we created two layouts, one with a **light** background and one with a **dark** one. + +Access Drive with your company account allows you to create a new presentation from one of the availabe templates (`Drive -> New -> Presentation -> From template` and choose the `Sparkfabrik GmbH` tab at the top). + +Instructions on how to make the best out of those layouts are in the first page of each template. diff --git a/content/resources/role-isc-junior-developer.md b/content/resources/role-isc-junior-developer.md new file mode 100644 index 0000000..2b2151a --- /dev/null +++ b/content/resources/role-isc-junior-developer.md @@ -0,0 +1,59 @@ +/* +Title: Impact Scoring Card - Junior Developer +Description: Junior Developer role in SparkFabrik +Sort: 50 +*/ + +## Mission + +* To realize technical solutions that satisfies customer's needs. +* To follow the direction of your team lead in doing so. +* To work following our agreed procedures and matching our quality standards. +* To value collaboration and critiques as the building blocks for trust with colleagues and customers. +* To value continuous improvement, seek out opportunities to learn and live by the principles of the Agile manifesto. +* To seek assistance every time you are in the need, not trying to shine by self-love or obstinacy. + +## Values + +* Passion +* Curiosity +* Communication + +## Awesomeness horizon + +If you score three times in a row over `2.5` you may get a career advancement. + +## Attitude + +### Teamwork + +You share your goals with your mates and work with them, never playing the hero or being a team of one. You speak your voice clearly, even when it's difficult, without holding relevant information for fear or stubbornness. When being frank makes you uncomfortable, you still strive to be polite and cheerful so you can make your point. + +### Self-organization + +Your own schedule and workload balance is your responsibility. You have clear what's expected to you each iteration (week, sprint, milestone) and step up to discuss conflicting priorities and possible bottlenecks with the management. + +### Lucidity + +You have clear what's expected from you and what you have to do to match the expectation. When you feel like you lost your goals, you speak up and do your best to have them clear. + +### Awareness + +You perceive the overall impacts of your day-to-day choices and know when to ask for validation. You face challenges proactively, not always waiting for others to solve problems for you, but know when to stop and ask for help to avoid wasting time or losing your mind on things bigger than you. + +### Strong opinions, lightly held + +You speak your mind and sustain your ideas with words and facts, but you are open to criticism and listen with open ears. + +## Business impacts + +* You define implementative details of solutions that fulfill business goals, matching our high quality standards. +* You realize solutions that fulfill business goals, matching our high quality standards, as defined with your team. +* You learn new, useful skills, taking advantage of any opportunity, balancing possible negative impacts on your duties. +* You help improve internal projects (even if just with bugfixes or documentation) based on your skills, aspirations and training goals. + +## Contributions + +* You propose or help to generate content about technology, methodology or practices for Sparkfabrik's media. +* You keep our Company Playbook up to date, extend and fix it every time you see the need. +* You deliver contributions (bugfixes, documentation, translations) to community projects based on your skills, aspirations and training goals. \ No newline at end of file diff --git a/content/resources/role-isc-lead-developer.md b/content/resources/role-isc-lead-developer.md new file mode 100644 index 0000000..7c25600 --- /dev/null +++ b/content/resources/role-isc-lead-developer.md @@ -0,0 +1,70 @@ +/* +Title: Impact Scoring Card - Lead Developer +Description: Lead Developer role in SparkFabrik +Sort: 70 +*/ + +## Mission + +* To understand customer's needs and help the customer state them in a clear, understandable form. +* To design systems that satisfies customer's needs. +* To guide your development team to implement those systems. +* To promote our procedures and standards and to find new opportunities to improve them. +* To teach by example and words, showing the value of excellence. +* To value collaboration and critiques as the building blocks for trust with colleagues and customers. +* To value continuous improvement, seek out opportunities to learn and live by the principles of the Agile manifesto. +* To contribute to the company's technical culture, sharing your mastery with others. + +## Values + +* Passion +* Discipline +* Teamwork + +## Awesomeness horizon + +If you score three times in a row over `2.5` you may get a career advancement. + +## Attitude + +### Leadership + +You are an organizational model for you colleagues. You live by best practices and require and help others to meet your high standards. You do your best to lead by consensus, listening to your team, but you always remember they look at you as a guide. You protect your team and remove obstacles but keep them committed and fit to create value. + +### Decisiveness + +You take promptly decisions, even on partial data, perceiving the overall impacts on people, schedule and deliverables. You face challenges proactively, not waiting for others to solve problems for you. You handle difficult situations without losing your mind and help others enduring them. + +### Teamwork + +You share your goals with your mates and work with them, never playing the hero or being a team of one. You speak your voice clearly, even when it's difficult, without holding relevant information for fear or stubbornness. When being frank makes you uncomfortable, you still strive to be polite and cheerful so you can make your point. + +### Self-organization + +Your own schedule and workload balance is your responsibility. You have clear what's expected to you each iteration (week, sprint, milestone) and step up to discuss conflicting priorities and possible bottlenecks with the management. + +### Lucidity + +You have clear what's expected from you and what you have to do to match the expectation. When you feel like you lost your goals, you speak up and do your best to have them clear. + +### Strong opinions, lightly held + +You speak your mind and sustain your ideas with words and facts, but you are open to criticism and listen with open ears. + +## Business impacts + +* You clearly identify the value behind a requirement and orient your work towards the delivery of that value, in accordance with our technical and human standards. +* You lead the creation of high-quality software, on time and in budget. +* You define the architecture of solutions that fulfill business goals, matching our high quality standards. +* You help your team define implementative details of solutions that fulfill business goals, matching our high quality standards. +* You sustain the growth of your younger colleagues, promoting the values of delivery quality and human relations both inside and outside the company. +* You help your team substantially improve internal projects, leading joint effort and/or directly contributing work as necessary. +* You shape new technologies, practices, tools and knowledge, even when you work on customer projects, in accordance with the direction set by the CTO. + +## Contributions + +* You generate content about technology, methodology or practices for Sparkfabrik's media. +* You lead, with the help of Sales and Communication, the production of a case study within two weeks by the end of each project. +* You make sure your team members (you also) participate in CFPs, applying as speakers at relevant conferences. You facilitate the organization of work to allow them (or yourself) to prepare the necessary material. +* You keep our Company Playbook up to date, extend and fix it every time you see the need. +* You deliver substantial contributions (new features, bugfixes, documentation, translations) to community projects, , leading joint effort and/or directly contributing work as necessary. diff --git a/content/resources/role-isc-professional.md b/content/resources/role-isc-professional.md new file mode 100644 index 0000000..3800dd8 --- /dev/null +++ b/content/resources/role-isc-professional.md @@ -0,0 +1,75 @@ +/* +Title: Impact Scoring Card - Professional +Description: Professional role in SparkFabrik +Sort: 80 +*/ + +## Mission + +* To make your unique skills available to the whole company. +* To help lead and senior development achieving their mission. +* To dominate complexity, chew difficulties and laugh in the face of pressure. +* To promote our procedures and standards and to find new opportunities to improve them. +* To teach by example and words, showing the value of excellence. +* To value collaboration and critiques as the building blocks for trust with colleagues and customers. +* To value continuous improvement, seek out opportunities to learn and live by the principles of the Agile manifesto. +* To contribute to the company's technical culture, sharing your mastery with others. + +## Values + +* Passion +* Availability +* Teamwork + +## Awesomeness horizon + +You are already topping the awsomeness level. The higher your score, the higher the reward. + +## Attitude + +### Advocacy + +You are the professional model for your colleagues. You represent the company both inside and outside and are actively involved in the promotion of our culture. You are an antenna for the company, picking up information essential to validate and shape our overall strategy, of which you are an active and informed part. + +### Leadership + +You are an organizational model for you colleagues. You live by best practices and require and help others to meet your high standards. You do your best to lead by consensus, listening to your team, but you always remember they look at you as a guide. You protect your team and remove obstacles but keep them committed and fit to create value. + +### Decisiveness + +You take promptly decisions, even on partial data, perceiving the overall impacts on people, schedule and deliverables. You face challenges proactively, not waiting for others to solve problems for you. You handle difficult situations without losing your mind and help others enduring them. + +### Teamwork + +You share your goals with your mates and work with them, never playing the hero or being a team of one. You speak your voice clearly, even when it's difficult, without holding relevant information for fear or stubbornness. When being frank makes you uncomfortable, you still strive to be polite and cheerful so you can make your point. + +### Self-organization + +Your own schedule and workload balance is your responsibility. You have clear what's expected to you each iteration (week, sprint, milestone) and step up to discuss conflicting priorities and possible bottlenecks with the management. + +### Lucidity + +You have clear what's expected from you and what you have to do to match the expectation. When you feel like you lost your goals, you speak up and do your best to have them clear. + +### Strong opinions, lightly held + +You speak your mind and sustain your ideas with words and facts, but you are open to criticism and listen with open ears. + +## Business impacts + +* You clearly identify the value behind a requirement and orient your work towards the delivery of that value, in accordance with our technical and human standards. +* You define the architecture of solutions that fulfill business goals, matching our high quality standards. +* You define implementative details of solutions that fulfill business goals, matching our high quality standards. +* You realize solutions that business goals, matching our high quality standards, as defined with your team. +* You sustain the growth of your younger colleagues, promoting the values of delivery quality and human relations both inside and outside the company. +* You own one or more internal projects making sure they are in good shape, documented and up to date. +* You shape new technologies, practices, tools and knowledge, even when you work on customer projects, in accordance with the direction set by the CTO. +* You participate with CTO, COO and other relevant company staff to cross-project strategy and tactics meetings. + + +## Contributions + +* You generate (or help to) content about technology, methodology or practices for Sparkfabrik's media. +* You keep our Company Playbook up to date, extend and fix it every time you see the need. +* You deliver substantial contributions (new features, bugfixes, documentation, translations) to community projects based on your skills, aspirations and training goals. +* You own one or more community projects making sure they are in good shape, documented and up to date. \ No newline at end of file diff --git a/content/resources/role-isc-senior-developer.md b/content/resources/role-isc-senior-developer.md new file mode 100644 index 0000000..dbf1faf --- /dev/null +++ b/content/resources/role-isc-senior-developer.md @@ -0,0 +1,58 @@ +/* +Title: Impact Scoring Card - Senior Developer +Description: Senior Developer role in SparkFabrik +Sort: 60 +*/ + +## Mission + +* To define and realize technical solutions that satisfies customer's needs. +* To follow the direction of your team lead in doing so. +* To help your junior mates grow, challenging them and giving them fishing cans, not fish. +* To work following agreed procedures and matching our quality standards. +* To value collaboration and critiques as the building blocks for trust with colleagues and customers. +* To value continuous improvement, seek out opportunities to learn and live by the principles of the Agile manifesto. +* To contribute to the company's technical culture, sharing your mastery with others. + +## Values + +* Passion +* Discipline +* Communication + +## Awesomeness horizon + +If you score three times in a row over `2.5` you may get a career advancement. + +## Attitude + +### Teamwork + +You share your goals with your mates and work with them, never playing the hero or being a team of one. You speak your voice clearly, even when it's difficult, without holding relevant information for fear or stubbornness. When being frank makes you uncomfortable, you still strive to be polite and cheerful so you can make your point. + +### Self-organization + +Your own schedule and workload balance is your responsibility. You have clear what's expected to you each iteration (week, sprint, milestone) and step up to discuss conflicting priorities and possible bottlenecks with the management. + +### Lucidity + +You have clear what's expected from you and what you have to do to match the expectation. When you feel like you lost your goals, you speak up and do your best to have them clear. + +### Strong opinions, lightly held + +You speak your mind and sustain your ideas with words and facts, but you are open to criticism and listen with open ears. + +## Business impacts + +* You define implementative details of solutions that fulfill business goals, matching our high quality standards. +* You realize solutions that business goals, matching our high quality standards, as defined with your team. +* You sustain the growth of your younger colleagues, promoting the values of delivery quality and human relations both inside and outside the company. +* You substantially improve internal projects (new features, bugfixes, documentation) based on your skills, aspirations and training goals. +* You shape new technologies, practices, tools and knowledge, even when you work on customer projects, in accordance with the direction set by the CTO. + +## Contributions + +* You generate (or help to) content about technology, methodology or practices for Sparkfabrik's media. +* You keep our Company Playbook up to date, extend and fix it every time you see the need. +* You partecipate in CFPs and apply as speaker at relevant conferences. +* You deliver substantial contributions (new features, bugfixes, documentation, translations) to community projects based on your skills, aspirations and training goals. diff --git a/content/resources/role-isc-supporter.md b/content/resources/role-isc-supporter.md new file mode 100644 index 0000000..90ca28a --- /dev/null +++ b/content/resources/role-isc-supporter.md @@ -0,0 +1,68 @@ +/* +Title: Impact Scoring Card - Supporter +Description: Role that owns administrative and support processes in SparkFabrik +Sort: 90 +*/ + +## Mission + +* To help the management achieving company's mission. +* To own support processes, improving them as necessary. +* To promote our procedures and standards and to find new opportunities to improve them. +* To value collaboration and critiques as the building blocks for trust with colleagues and customers. +* To value continuous improvement, seek out opportunities to learn and live by the principles of Lean Thinking. +* To contribute to the company's organizational culture, sharing your mastery with others. + +## Values + +* Tidiness +* Reliability +* Teamwork + +## Awesomeness horizon + +Your role has no ladder as it is vital to the correct working of the company. The higher your score, the higher the reward. + +## Attitude + +### Clarity + +You are an organizational and procedural reference for both employees and management. You live by and shape clearly defined practices and help others creating new ones. + +### Fluidity + +You do your best to facilitate administrative and organizational processes. You build bridges across the whole company and work hard to highlight and remove wastes and obstacles as you identify them. You listen what happens at all levels and help both management and workforce find a common ground when you feel they lack the proper alignment. + +### Proactivity + +You know when to take promptly decisions, even on partial data, or require management validation. You perceive the impacts your choices will have on the company and make sure you always work to fulfill the current strategy. You face challenges proactively, not waiting for others to solve problems for you. You handle chaotic situations without losing your mind and help others making sense of them. + +### Teamwork + +You share your goals with the management and work with them. You also explain your needs or decisions to the workforce so that they'll be on your same page and understand the real value you want delivered. You speak your voice clearly, even when it's difficult, without holding relevant information for fear or stubbornness. When being frank makes you uncomfortable, you still strive to be polite and cheerful so you can make your point. + +### Self-organization + +Your own schedule and workload balance is your responsibility. You have clear what's expected from you and step up to discuss conflicting priorities and possible bottlenecks with the management. + +### Lucidity + +You have clear what outcomes are expected from your work and what you have to do to match the expectation. When you feel like your goals or process outcomes are confused, you speak up and do your best to have them clear. + +### Strong opinions, lightly held + +You speak your mind and sustain your ideas with words and facts, but you are open to criticism and listen with open ears. + +## Business impacts + +* You implement and improve administrative and support processes to bring a positive impact on the day-to-day work of the whole company. +* You sustain the growth of your younger colleagues, promoting the values of delivery quality and human relations both inside and outside the company. +* You own one or more internal processes, making sure they are in good shape, documented and up to date. +* You shape new practices, tools and knowledge, while working on your daily duties, in accordance with the direction agreed with the management. +* You participate with the company governance and other relevant company staff to cross-project/cross-process strategy and tactics meetings. + + +## Contributions + +* You generate (or help to) content about tools, methodology or practices for Sparkfabrik's media and playbook. +* You help the workforce to organize, collect or shape information necessary for them to own public contributions that will bring benefit to the company. \ No newline at end of file diff --git a/content/resources/sort b/content/resources/sort new file mode 100644 index 0000000..c5b431b --- /dev/null +++ b/content/resources/sort @@ -0,0 +1 @@ +50 \ No newline at end of file diff --git a/content/our-company/approved-hardware-and-software.md b/content/tools-and-policies/approved-hardware-and-software.md similarity index 95% rename from content/our-company/approved-hardware-and-software.md rename to content/tools-and-policies/approved-hardware-and-software.md index 7195cf6..544f1a5 100644 --- a/content/our-company/approved-hardware-and-software.md +++ b/content/tools-and-policies/approved-hardware-and-software.md @@ -1,3 +1,8 @@ +/* +Description: How we require you to care in your devices during your daily work at SparkFabrik +Sort: 60 +*/ + SparkFabrik is primarly a web-development company, dwelling in the realm of FOSS (Free and Open-Source Software). We are strictly tied to the Unix world, either in philosophy, technics and mindset. diff --git a/content/working-principles/communication-channels-and-register.md b/content/tools-and-policies/communication-channels-and-register.md similarity index 100% rename from content/working-principles/communication-channels-and-register.md rename to content/tools-and-policies/communication-channels-and-register.md diff --git a/content/tools-and-policies/sort b/content/tools-and-policies/sort index f599e28..209e3ef 100644 --- a/content/tools-and-policies/sort +++ b/content/tools-and-policies/sort @@ -1 +1 @@ -10 +20 diff --git a/content/tools-and-policies/tasks-and-time-tracking.md b/content/tools-and-policies/tasks-and-time-tracking.md new file mode 100644 index 0000000..c71f895 --- /dev/null +++ b/content/tools-and-policies/tasks-and-time-tracking.md @@ -0,0 +1,97 @@ +## Basic principles + +Working as a team, and loving order and focus, we want to keep track of all our tasks. +There are a bunch of reasons for this: + +1. Since our time on projects is charged to the customers, we want (!) them to know on what we spent our time +1. Having tracked tasks allow for project leaders, peers and customers to negotiate their priorities +1. We don't want ambiguity when we communicate: tracking tasks we can refer them with piercing precision using IDs +1. When a task is properly tracked and described, everybody in the team can work it out (trading off efficiency for efficacy maybe, but still) + +At the same extent, we want to track the time we spend on task so that: + +1. We can report it to client +1. We know if we are exceeding our budget or more basically how much we have spent +1. We can have metrics related to tasks life-cycles, etc. + +We **don't want** to measure velocity or speed of individuals. Everyone has her own pace. +Velocity rates are kept into consideration for the whole team, with the goal to continuously improve its effectiveness, remove obstacles, make them work less to produce more, etc. + +We appreciate people setting personal goals on proficiency or productivity but to us it's not as a matter of sheer speed, so time is only one of the variables. + +### Tracking tasks + +We track our tasks on [Gitlab](https://gitlab.sparkfabrik.com). + +Tasks can be tracked directly by us, mostly when working on projects with a backlog of items to be developed; or can be tracked by the customer on boards representing maintenance or support activities. + +Credentials are needed to log into our tracker and work on projects. + +### Tracking time + +We track time on [Toggl](https://toggl.com). Each member of SparkFabrik will be provided with a Toggl business account and will be able to track time on company projects and tasks. + +There are rules to keep things consistent between the tools so that we can make something out of all these data. + +## Tracking policies + +Talking about our everyday work, we recognize three different type of activities: + +* **Approved tasks**: this is what the customers usually call us for. These activities are described in a signed agreement of sort, have a budget, a deadline and deploy a deliverable (even intangile, like a training course or T&M consultancy). +* **Warranty**: this is what the customer wants done but does not expect to pay for. Fixing a bug or amending an issue which is due to us, for example. +* **Support**: this is the time spent to deliver the _approved_ tasks_ or to help a customer getting what he need, not only in term of deliverables. These activities are often (not always) in charge to project or customer leads. + +We track time differently for those activities. + +As a general rule, all time entries must contain links to specific issue codes when available; in addition remember the description line always is a gift to your future self, since you may be required to explain the admininistration or the customer why you spent that time and on what. + +| Issue ID and title | Good time entry description | Bad time entry description | Very bad time entry description | +| ------------------ | --------------------------- | -------------------------- | ------------------------------- | +| `#123 Problems with contact form` (bug) | #123 - Verified steps to replicate the bug | #123 Problems with contact forms | Analysis | +| `#345 The user can register to site` (feature) | #345 - Login form styling | #345 - Development | Development | +| ``| Call with John Doe about new feature; tracked issue #789 | Call with John Doe | Phone call | + +### Approved tasks + +> **Forenote**: Despite we try to group tiny activities to form a _3+ working days whole_, it happens that we must deliver very small tasks to our customers, such as one-shot security upgrades or very small changes to a living product. +> Such small, isolated activities, must be tracked under the [Support](#support) rolling task (see below). + +Each task approved by a customer/for a project is tracked on Toggl as a `Task` (heh!), with the format `[Task ID] Task Name`, where `Task ID` is an internal reference code, in the format `YYYYMM[DDII]` (where `DDII` is an optional part composed by two-digits day (`DD`) and a discriminant incremental), and `Task Name` is a mnemonic description such as `Website development`, `New media gallery`, `Q3 Maintenance` etc. + +Approved tasks have a time budget on Toggl and the tracked time is counted against that time budget. Should a customer extend the budget, the task will be updated/extended or a new task will be created, depending on what makes more sense in the context. + +Project/Customer leads should take care of keeping things consistent in terms of issue tracking, using [Gitlab's Milestones](https://docs.gitlab.com/ee/user/project/milestones/). Create a milestone with the same name as the related task (`[Agreement Code] Task Name`) and add all issues partaining to this task in there. + +### Warranty + +Each customer project has a _Warranty_ task in it. This is a "rolling" task, in that it has no time budget assigned. Administrtion will get a monthly chunk of the time entries for reporting. It is important to undestand that, should we discover that a warranty issue is not actually covered by warranty (it happens sometimes), we will move it where it belongs (Support or other tasks): to this extent, **it is mandatory that each time entry refers to an issue on the tracker**. + +### Support + +Most of the time, who stands in the front line is most likely to track time under this task. As the _Warranty_ task, this is also a rolling activity and we can see it as a catchall for the many different tasks a project/customer lead must undergo from day to day. + +It is very unlikely that you can refer an issue for such type of activities: having a phone call, reviewing the project status, replying mails etc have too much overhead in tracking. To make some distinction during reporting and lifecycle analysis, there is four tags to apply to time entries that falls under _Support_ umbrella: + +* **Customer care**: when you help a customer doing stuff or making sense out of something. +* **Estimation**: when you devote time to estimate new features, projects or improvements. +* **Project Management**: all activites partaining to helping the team and the customer getting _approved tasks_ done (agile events, validation, grooming, etc)- +* **Issue checking**: when an issue is raised you may have to spend time making sure it is properly detailed or to verify it is actually relevant (think about bug tracking for example). Here is where you'll track such time. + +Not all these entries will result in a cost for the customer, so don't worry about this: **just track everything you do**! You will be engaged in analysis by the administration during the reporting phases. + +In addition, all time entries for those very small activities agreed with the customer by mail or without a purchase order, which we performe from time to time, such as security updates, small and sporadic changes, etc, must be tracked as `Support`. When you track a `Support` entry of that kind **it is important that you refer to an issue and provide a sound description** since no written contract or purchase order will help us track the request during reporting. + +#### Support tags examples + +Find below some examples on how to use those tags. + +| Source | Event | Tag | Notes | +| ------ | ----- | --- | ----- | +| Client | `I can't remember how to insert a news on the site, can you help me?` | `Customer Care` | The customer can be expected to be trained on this, or to keep notes, so you are actually supporting it. | +| Client | `I need you to reschedule releases since the marketing asked` | `Project Management` | The customer can't do this without our involvement. This activity helps providing the correct service. | +| Team | `Let's take some time to groom the backlog and refine estimation` | `Project Management` | All partecipants have to track individual entries; despite this involves estimations, the activity is necessary to keep things on track and is not triggered by the client that needs cost-related information for his decisional process. That's why it is tagged as `Project Management`. | +| Client | `The site is not working as expected, we have filed a bug` | `Issue checking` and if it is indeed a bug, move time entry to `Warranty` | We will check the issue, the provided information and verify it is a bug (our fault). If this is the case the whole time spent will be classified as warranty effort. | +| Client | `I may need a new feature/an improvement; is this technically feasible?` | `Issue checking` | This may involve the whole team, in which case all will have to track under this task and tag. | +| Client | `Can you please provide an estimation for this new feature so we decide if we want to pay for it?` | `Estimation` | | +| Sales | `I need help from your team to estimate a new project` | `Estimation` | All partecipants have to track individual entries; If the new project falls under an existing main project, use the `Support` rolling task of the main project; in case of new clients with no main project, track the entries on `Sparkfabrik Internal -> Sales` tagged as `Estimation`, and name the customer in the description. | +| You | `I really need to keep track of those request e-mails and set their priorities` | `Project Management` | There are customers that for contextual reasons won't use our tracker and will keep going the same old root. Our task is to keep things tidy and organized and this is management and ownership. | \ No newline at end of file diff --git a/content/working-at-sparkfabrik/career-advancement.md b/content/working-at-sparkfabrik/career-advancement.md new file mode 100644 index 0000000..5af3c61 --- /dev/null +++ b/content/working-at-sparkfabrik/career-advancement.md @@ -0,0 +1,40 @@ +/* +Description: How people grow and specialize in SparkFabrik +Sort: 40 +*/ + +People in Sparkfabrik should expect to advance on their career path almost constantly. +Growth is awarded by the combination of two mechanisms. + +## Length of service + +We value people to stick with us. +Turnover is costly and investement on team building pays more in the long term. That's why we want people to stay around. We reward anyone with a salary increase after 3, 5, 7 and 10 years of work. This happens automatically, regardless of performance and will go beyond the tenth year. + +## Impact scoring + +This practice is heavily inspired by how [Deeson](https://www.deeson.co.uk) and [Stack Overflow](https://stackoverflow.com/) help their employees achieve their goals and commit to their duties. + +Once every three months, as a developer, you attend an [1:1 meeting](/working-at-sparkfabrik/one-to-one-meetings). Among other things, [Impact scoring](/working-at-sparkfabrik/impact-scoring) will be evaluated and discussed in that occasion, to measure your growth on the various business-impacting aspects. + +Matching (or exceeding) a score of `2.5` for three times in a row will allow you to be assigned a higher role. Stepping up on your career path will then be based on adherence to values and the actual impact you make, not on personal perception of your merit. + +Stepping up will impact: + +* your salary following [this table](/working-at-sparkfabrik/salaries#salary-variations); +* your duties in accordance to your new [impact scoring card](/resources/impact-scoring-cards). + +``` +NOTE: Salary brackets values and direct bonds between performance and salary step-ups are still in "alpha" stage. +``` + +## Taking the challenge + +To fullfill [its vision](https://www.sparkfabrik.com/en/who-we-are.html), Sparkfabrik sells and cultivates high seniorities. Thus we expect junior developers to work hard to step up and we **require** that, once the proper goals are completed they will be ready to take the responsibilities of a senior developer. + +Not all senior developers crave to become leaders or top professionals, instead. This is understandable and we respect the choice. +When you as a senior developer meet the requirements for a career advancement, we will present you the opportunity, explain new role's benefits, expectations and duties. It is to you to take or leave. + +We encourage everybody to accept the challenge and may, in many cases, probe people that already refused if we see a new occasion for them to shine, but won't push or force any advancement. + +Still we expect **every senior developer** to constantly increase her scoring and set new professional goals, maybe tackling new [Specialities](job-roles/operations#specialities) in their career, making side steps instead of climbing the ledder. \ No newline at end of file diff --git a/content/working-at-sparkfabrik/hiring-from-abroad.md b/content/working-at-sparkfabrik/hiring-from-abroad.md new file mode 100644 index 0000000..78fad6b --- /dev/null +++ b/content/working-at-sparkfabrik/hiring-from-abroad.md @@ -0,0 +1,104 @@ +/* +Description: Things to know if you want to move to Italy +Sort: 35 +*/ + +We are very happy to receive application from around the globe. +Actually we like SparkFabrik to be a multicultural melting pot, where ideas can spark (heh!) from our cultural differences and richness. + +In this page we summarize what we know about relocation processes for people coming to Italy from foreign countries. +We are pretty new to this and Italy is a very bureaucratic country, where procedures tend to change over time, so we won't go into too much details here. The following overview will hopefully clarify what to expect and help our personnel and the candidate to be on the same page, should we embark in the process. + +## Relocating from EU + +Citizen of EU Countries can move freely to Italy and take advantage of an unrestricted labour market. +This means that **relocating is as simple as finding an accommodation and signing the employment contract**. Easypeasy. + +## Relocating from outside EU with Blue Card + +Moving from outside EU for working reasons requires the issuing of the Blue Card, an EU permission to practice in european area. Issuing a Blue Card in Italy is allowed only for _high specialization_ professionals so **you must be graduated (Bachelor's degree or higher) in Computer Science or Computer Engineering** for us to request the emission of a Blue Card. + +### Steps to obtain a Blue Card + +#### 1. Obtain a _Declaration of Value_ + +This document states that the graduation you achieved in your country qualifies as an Italian Bachelor's degree (or higher). +The Italian Embassy or Consulate in your country can release one for you (contact your university if in doubt). **This is usually the step with the longer elapse**: how much it will take depends on your country's bureaucracy and disposition to emigration of specialized labourers. +Once you got it, make a copy and send the original to us **with a fast and secure shipment**! We will need it to make our request for your visa. + +#### 2. Sign a Letter of Intent + +We will sign an agreement about your hiring, clearly stating your job role, you salary, the duration of the contract (usually permanent) and other details. + +We can sign the agreement remotely or you can come visit (yay!). If you decide to come visit, ask your local autorities for a tourist visa. In those cases where traveling costs too much, you can send an original signed copy. In this case it's adviced to **send it alongside your Declaration of Value**, since we will also need the original letter to make our request. +Of course we'll send you our signed copy also! + +This step will actually go in parallel with the previous one. + +#### 3. Send the request for your Blue Card + +This is on SparkFabrik. We will make formal request for a Blue Card in the light of your professional qualification and our will to hire you. + +Your country will have then to evaluate the request and issue you a **visa to permanently move to Italy**. +We need you to send a color scan of your passport (relevant pages) that clearly shows the visa. The visa number must be clearly readable, since we'll have to attach it to book the appointment for your Blue Card. + +Almost there... + +#### 4. Book all the things + +Once you have the visa we can book what's necessary: + +* We'll agree on a possible arrival date and you'll book your flight. +* We will book your hotel for the first month. +* We will book the appointment in local Prefecture to sign your Blue Card contract. We can not guarantee for the date of that appointment but the sooner we'll book, the sooner we'll get it. + +The day after the appointment (the same day won't work) we'll go together to a local post office to send your request for registration to the immigration offices. +The Blue Card (and residence permit) will be issued after you will go for your registration, but **with the postal receipt we can proceed with your hiring**. + +#### 5. Hiring + +Your hiring will legally begin from the day after you get the receipt. +**As soon as you'll have your postal receipt you will sign your hiring contract and we'll take care of the rest**. + +#### 6. Registration + +With your postal receipt you will also get a date for **an appointment to the immigration offices**. You'll have to leave your fingerprints and other information. After the registration you will be issued your Blue Card and the process will finally be over. + +### Our role + +We will take care of collecting all the documents if not for your Declaration of Value (you must provide it on your own, sorry). +We will be present during all the necessary steps, so you don't get lost in bureaucracy or with possible non-english-speaking operators in the various offices. + +### Costs + +Of the costs involved in your relocation, SparkFabrik will cover: + +* The hotel for the first 30 days. Having a 30 days long accommodation is mandatory to book the appointment in Prefecture. +* The costs of all the paperwork (stamps, postal expenses, etc). +* Meals vouchers (lunch) for your first days of staying in the office before your actual hiring (see caveat #1 below). + +Your flight, local transportation and other expenses are supposed to be on you. + +We are working to switch to a relocation fee model, reimbursing a flat fee of ideally € 1.000 for you to spend as better fit your moving plan. +Mind thought that you will still have restrictions on your accommodation for the first 30 days so that it will be apt to require the Blue Card. + +### Caveats + +1. There will be **a gap between your arrival and the appointment you will have in prefecture for the Blue Card contract signing**, plus two more working days from the signing to the legal hiring. We'll do our best to shrink that gap but since it doesn't entirely depend on us, it is better to **take into account 7 to 15 days passing between your arrival and your actual hiring**. Of course, during that period you will be a welcomed guest to our offices so you can get acquainted with the environment and the people and possibly get to know something on how we work. + +2. As an immigrant from outside the EU you will have to attend 2 days of civic education. The training calendar will be provided when your sign your Blue Card contract. If for any reason you won't be able to attend an event **you must provide proper justification** or you'll invalidate your Blue Card request. The training has no costs. SparkFabrik won't count the training days as leave or off-time, they'll be on us. + +3. For a incoherent regulation, **you can be hired with the sole postal receipt but you can't have an italian bank account without a definitive residence permit**. Since italian companies are bound to pay wages with traceable transitions, in the first couple of months or so (depending from when you'll get your registration appointment), we will have to either pay you on a foreign bank account or paying you with checks. In the second case, you will have to change checks in cash at our bank branch. This is an annoyance we are working to solve. + +4. For bureaucratic reasons, **passing the first 30 days in a hotel is the quicker way to activate the Blue Card contract procedure**. There are other options but they will take (way) longer. Among them, you may want to rent an apartment before your trip. In this case, consider that you will have to produce all necessary documentation for a legal rent agreement by the day of your appointment in Prefecture. In addition you will need to already have an italian Fiscal Code, which basically means you have already been in Italy in the past. If you want to go that way SparkFabrik won't be able to act on your behalf, nor to refund your costs. We will still do our best to help on a practical perspective, like talk to the apartment owner, collect physical documents and the like. +Since 30 days pass fast, our advice is to begin to look anyway for a more stable accommodation in the days before your departure. Finding accommodations in Milan may be a non trivial task depending on your budget, your expectations and the period of the year. As above, we can provide best-effort help, contacting a shortlist of locators of your choice. + +## Relocating from outside EU with a Green Card + +If you have relatives in Italy, asking for a family reunification Green Card may be faster. + +This permission is available to everyone with a strict relative (parent, child or spouse) who is an italian citizen or have obtained a regular residence permit. To be entitled for such Green Card you must enter Italy with the proper visa (for family reunification). Ask your local authority how to obtain one. Mind that in case you declare the relative is a spouse, cohabitation is necessary to obtain such Green Card. + +SparkFabrik can't help in obtaining such Green Card but the permit allows for normal hiring, exactly as a Blue Card. + +Should the relationship that sustains the Green Card cease (divorce, death or other events) while you are already hired, the Green Card can be converted to a Blue Card with a simple request. diff --git a/content/working-at-sparkfabrik/impact-scoring.md b/content/working-at-sparkfabrik/impact-scoring.md new file mode 100644 index 0000000..4ff1ec3 --- /dev/null +++ b/content/working-at-sparkfabrik/impact-scoring.md @@ -0,0 +1,56 @@ +/* +Description: How we manage performance and rewarding in SparkFabrik +Sort: 60 +*/ + +As every fast growing company we faced the problem of unbiased performance and rewarding mechanisms. + +## Credits + +We stumbled upon [Deeson's model](https://handbook.deeson.co.uk/working-at-deeson/impact-scoring/), which in turn is claimed to be borrowed from [Stack Overflow](https://stackoverflow.com/company/salary/skills/web-developer?e=1&l=1) in the first place so credits go to those two exemplary companies for shaping the model. Thank you guys! + +## Impact scoring + +We evaluate each other based on the desired impact we should get during our daily work. To this extent each role's duties in Sparkfabrik is detailed based on the expected outcomes, not a series of tasks or procedures that people must follow blindly. + +These outcomes is seen as important to business, context and company culture by [company governance](/organization/governance). + +## Impact assessment + +In [one-to-one meetings](/working-at-sparkfabrik/one-to-one-meetings) at the start of every quarter (Jan, April, July, Oct), we evaluate a developers against the outcomes listed in their [impact scoring cards](/organization/roles-accountabilities#per-role-accountabilities) on the same scale from A (and above) to C used by Deeson. + +Each outcome or skill gets one of the following rates: + +* **A+++**: Over the top amazingness. You do, teach and lead. When people think of this skill, they think of you. Even in Sparkfabrik, where people are expected to excel, such a score will be rare. You can aim here but are not expected to, probably this reflects an aspect of your personality or a natural talent. +* **A+**: You do more than your mates expect, even considering we have demandingly high standards. +* **A**: You totally do what's expected, matching our high standards. Undeniably positive impact. +* **B**: Good performance but with improvement headroom. When you have to set your quarterly or yearly professional goal, here is where to put your energy first. +* **C**: This falls way behind our expectations and you need to improve significantly in this area. Such a score will inevitably set a goal for you for the next quarter, when this is expected to have become a B. Scoring the same C over and over is not acceptable. + +An additional value is + +* X – Who is providing the score have no evidence or data to evaluate you on this aspect. + +## Total score calculation + +The total score is calculated by the following formula: + +> (4 x _A+++ count_ + 3 x _A+ count_ + 2 x _A count_ + 1 x _B count_ + 0 x _C count_ + 0 x _X count_) / (_Total aspects count_) + +The resulting score is and average awesomeness indicator you can keep track of. It is bound to grow and when it constantly stays over the _Awesomeness horizon_ reported in your impact scoring card, you'll be eligible for a [career advancement](/working-at-sparkfabrik/career-advancement). + +## How assessment happens + +This evaluation is not done by someone in a vacuum. **You are required to attend the one-to-one with a complete score-card** you will have filled with your lead (or senior mate). This means you will have to discuss your scoring, not getting it _from above_. + +If you feel you got an unfair scoring from your lead, **you can have a HR representative to review the evaluation** with you and your lead in advance. + +### For the evaluated + +Although other people may not always be objective in evaluating your impacts, it is important to sustain the conversation openly and get all the reasons behind each score. Even when it's difficult to take, **honest feedback is the most valuable help you can get in your growth**. +Different people will see you in different lights and from different perspectives. This is also food for thought and will help you nurturing soft social skills, useful when you will become a team leader or a top manager. + +### For the evaluator + +It may be difficult and uncomfortable to give honest feedback. You may be tempted to be too soft, too rewarding, shy away from harsh topics, etc. Or, quite the opposite you may be in rage for something really bad that recently happened and be tempted to bash your colleague with a bad evaluation, calling off months of good work and wiping the slate clean. +Having to explain your reasons should help you be more objective. Should the conversation become difficult, try to make her clear how she may succeed in the future instead that just pointing out how bad she failed. But don't sweep the dirt under the carpet. **Remember that the reason you are providing feedback is to allow your mate to do a better job next time**. Always trust she will! diff --git a/content/working-at-sparkfabrik/job-interviews.md b/content/working-at-sparkfabrik/job-interviews.md new file mode 100644 index 0000000..098ad66 --- /dev/null +++ b/content/working-at-sparkfabrik/job-interviews.md @@ -0,0 +1,242 @@ +/* +Description: How we perform recruitment meetings and assess skills in SparkFabrik +Sort: 20 +*/ + +We are constantly evolving our hiring skills and practices. + +What follow is a broad depiction of our hiring workflow, from first contact to job offer signing. +[Resource onboarding] has its own dedicated chapter in this playbook. + +## How we collect CVs + +Candidates apply via our company website or by mail, to jobs@sparkfabrik.com. +Please send your CV in the format that more represents your skills and attitude. Beside your CV a bit of a presentation is very welcome as it can help us understand who you are and what you expect from us. + +## First interview + +We'll propose you a one-hour slot for a first interview. We'll both collect information about each other and will keep a record of our discussion for future reference. +We do our best to get an interview with each and all candidates. Taking the first interview is not binding. If both we and you will be interested in establishing a job relation, we'll proceed to next steps. + +The first interview has the following goals: + +* Getting to know you, your attitude and your expectations in person. +* Giving you a taste of how working for us would be. + +Let's get this out of the way: **we will value our personal impression more than any of the following parameters**. +Anyway, we'll ask you some question and score your replies. Here is how we calculate your scores. + +### Knowledge of the company + +**Max score: 6** + +* You actually know what we do +* You read our [manifesto](https://www.sparkfabrik.com/en/manifesto.html) +* You read this playbook +* You know you offer something we are looking for +* You know we offer something you are looking for +* You get in touch with us in a non-fortuitous occasion (conferences, events, following on socials, etc) + +### Self awareness + +**Max score: 5** + +* You can show you know your strenghts +* You can show you know your weaknesses +* You can elaborate on what you expect from your professional life (short, mid and long term) +* You are aware about how you see yourself in our company +* You can explain why you really want to work with us + +### Attitude and personal skills + +**Max score: 4** + +* You can show passion for what you do, or what you want to do +* You have drive and will, not only at work +* You display or prove good social skills +* You show curiosity and interest about your future in our company + +### Proficiencies + +**Max score: 3** + +* You can clearly elaborate on the skills mentioned in your CV +* You can show some of your work (either personal or professional) +* You can fluently hold a part of the conversation in English + +More notes may be taken our side and maybe we won't go deep into each and every point here, but basically that's what we want to understand about you. + +During the interview we'll devote 10 to 20 minutes replying your questions about the company. +In addition, if you have any financial expectation, please be prepared to state it clearly during the first interview. + +We commit to provide you with a honest feedback within two weeks from the interview. We may also ask your feedback about how the interview went so we can improve our practices. It would be great if you agree to be engaged in such a loop. + +## Technical interview + +Given you roll a critical hit during your first interview, we will call you back to hold a technical interview. + +What "technical" means actually depends on your profile. Maybe you applied as a developer, UX designer, cloud engineer, agile product owner or whatever else. No matter what, in your technical interview we will get a grasp on your real proficiency and operational attitude. We will also answer your questions about how we do things and why. It has to be a conversation so we can both bring some value home. + +Your technical interview score will depend on various aspects, not just production skills. + +### Basic skills and experience + +**Max score: 7** + +* You have good fundations of Computer Science (high-school diploma or college degree, or analogue training) +* You have professional development experience with the programming languages we use the most +* You have professional development experience with the programming frameworkds we use the most +* You know how to test your code and you do it as a standard practice +* You use git in a non-trivial environment (i.e. contribute to projects on github, working in a medium/large team with defined branching model) +* You feel comfortable moving around a Unix shell and may use a Unix-like OS as your main operating system +* You know what Docker is and you make use of containers during your daily job +* You have basic experience with mainstream Cloud vendor services + +### Advanced skills and experience + +**Max score: 9** + +* You have experience engineering and designing complex/multi-service software architectures +* You have experience with serverless architectures +* The mentioned experience relates to the same technologies we are currently using +* You properly document your source code by automatic tools +* Containerized environments are common practice for you +* Continuous Integration is common practice for you +* You have experience with Continuous (or automated) deploy and delivery +* You know how to optimize your application performance +* You know how to check and fix security issues in your code +* You can articulate on your debugging approach, practices and tools +* You have strong experience with mainstream Cloud vendors services +* You have real-world experience with Kubernetes orchestrator +* You are or have in the past been a sysop + +### Soft skills + +**Max score: 8** + +* You can explain how you organize your work to ensure it to be on time, in budget +* You owned a project from both techcnical and organizational sides +* You have experience leading a team on medium/long term projects +* You feel comfortable speaking to an audience +* You are a good communicator +* You can manage a troublesome customer +* You can manage a troublesome colleague +* You provided technical mentorship (or onboarding coaching) to your junior colleagues + +### Agile skills and expertise + +**Max score: 7** + +* You have experience or training in Agile frameworks +* You know what a backlog is +* You played the Product/Project/Process Owner role in a Scrum or Kanban team +* You played the Scrum Master role in a Scrum team +* You was part of a development team using Scrum or Kanban and you can articulate on your experience +* You are certified in one of the named frameworks +* You can explain when and why it is not adviced to use such approaches + +### Passion and contributions + +**Max score: 5** + +* You can show passionate about the work we (us and you) do +* You contribute to FOSS projects +* You maintain or own FOSS projects +* You organize or help the organization of relevant events +* You talk to events, engage in hackathons or are active in a community. + +The technical interview may run from 60 to 90 minutes depending on your proficiencies level, your argumentations and how much fun we all take from it. + +Having the opportunity to take a look at your code or attending a bit of a performance during the interview will surely add useful information and may make you jump the technical challenge if it is totally clear that you are a great fit. + +Of course we are available to give you back information on our technical approach and setup so you can decide if SparkFabrik is a good fit for you also. Ideally we will reserve 10 to 20 minutes out of an hour for your questions. In addition, clever questions often matter more than correct responses. + +## Technical challenge + +Depending on your areas and level of proficiency, we may ask you to endure a technical challenge. The main goal of this activity is to see you at work in our environment. + +Technical challenges here are not setup like school exams and there is not always a bar to skip. It is more of a benchmark that will give us an idea about: + +* How you jump onto problems and tackle them +* How you face a healthy stress +* To what extent you can relate to others around you +* How proficient and productive you are during a (non standard) working day + +On the other hand we want you to: + +* Taste the general mood of our working environment +* Spend some times with your possible colleagues, like coffee-machine chat or lunch together +* Make questions about how we do things and why +* Speak your voice + +Depending on your availability, geographical position and other possible constraints, we can arrange the challenge to be taken _in person_ or remotely. + +### In person challenges + +In this case the actual challenge may change: you might have to produce something with a given technology, analyze a problem and provide your observation, explain and comment on something you produced in your spare time, dismantle a messy requirement in a set of user stories, reproduce a diabolical visual with CSS, or such. + +No matter the challenge nature, you'll be assigned a mentor for it, so you know whom to talk to in case of need. + +During in person challenges you'll have access to the internet, our team, our offices and all the devices, tools and boons you would reasonably get in your everyday job. + +### Remote challenges + +Moving to our offices for the time necessary to take a challenge is not always feasible. For those cases we will ask you to engage in a fictional project development using a Trello agile board. + +We have some **Technical Challenge board templates** availabe for you to clone right away. Each board lists all challenge instructions and rules, together with some useful resources. + +The board also sports a product backlog, describing a fictional product or agile activity. The backlog may be taken in charge directly in the board. A column for notes and asynchronous discussions is also there. + +To take the challenge you must: + +* Clone the board +* Put your name in the board title so we can find your one +* Invite your SparkFabrik mentors to the board (generally the CTO and HR responsible for your hiring) +* Start working on the project + +Your assigned mentor will play the role of the _Product Owner_ for this fake product. +The base technologies may change, depending on what's relevant in your specific case. + +To date the following remote challenge template boards are available: + +* [SparkFabrik development challenge](https://trello.com/b/iZpT5tIa/sparkfabrik-development-challenge-template): develop a simple web application to store and retrieve quotes on a technology of our choice. + +Please, be available to come visit or attend a 2-hrs call to present your work, review it with us and collect our feedback. + +At the end of your challenge you will be assigned a score, like follows. + +### Social attitude + +**Max score: 3** + +* You reached out for help or a simple review by your mentor +* You managed to controll stress and kept a positive mood along the activity +* You spent some time with other colleagues and learned about how life in SparkFabrik actually is + +### Self organization + +**Max score: 3** + +* You were able to set and maintanin tasklist to achieve your goals +* You managed to keep track of your progresses during the day +* You shown a clear understanding of your goal and can articulate about your progression (no matter how much) at the end of the challenge + +### Technical skills + +**Max score: 4** + +* You produced something that actually works +* You can explain (sell?) your choices and tradeoffs +* You can engage in a meaningful conversation with your mentor about how the challenge went, possible improvements and the difficulties you encountered +* Your work is testable, be it by automated tests or by a human following clear scenarios + +### Boons + +Any of the following may increase your score. + +**Max score: 4** + +* It is clear you took fun in the challenge +* You helped us shape the challenge idea or raised the stake +* You put special care in some valuable aspects of your deliverable +* You provide honest and professional feedback on your experience that can help us shape future challenges diff --git a/content/working-at-sparkfabrik/one-to-one-meetings.md b/content/working-at-sparkfabrik/one-to-one-meetings.md new file mode 100644 index 0000000..febca35 --- /dev/null +++ b/content/working-at-sparkfabrik/one-to-one-meetings.md @@ -0,0 +1,39 @@ +/* +Description: How we make sure people grow and express themselves in SparkFabrik +Sort: 80 +*/ + +Our one-to-one meeting is heavily inspired in spirit and practice by the [24 questions to ask in your next 1:1 meeting](https://www.small-improvements.com/blog/24-questions-ask-next-11-meeting/) post by Jason Lauristen on _Small improvements_ blog. + +HR representative and team leads engaging in one-to-ones with developers are required to read the whole post and take inspiration. + +## Scheduling + +Three (3) one-to-one meetings are scheduled each year. All employees with a role in operations will attend the meeting with a designated HR representative. +Each employee must [get ready for the meeting compiling her ISC](/working-at-sparkfabrik/impact-scoring#how-scoring-happens) with her team leader. +Optionally junior developers ISCs [may be compiled with the help of a senior team mate](/working-at-sparkfabrik/impact-scoring#how-scoring-happens) and their one-to-one conducted by a lead developer. + +## Goal + +The one-to-one meeting is **not** an occasion for control or top-down education. It is a meeting **of the employee and for the employee**, with the following goals: + +* Receive honest feedback +* Provide honest feedback +* Discuss impediments +* Setting near-range goals and check the milestones + +## Agenda + +To achieve meeting goals we set the following agenda over a 60 minutes meeting: + +1. **Warm-up** (5 mins): What is the single most important thing we need to discuss today? +2. **Celebration** (10 mins): What are your most significant accomplishments since we last met? Did you already match the goals you set last time? +3. **Impediments** (15 mins): What obstacles are you encountering right now? Where do you struggle? +4. **Next goals** (15 mins): What are the most important things you will focus on before we meet next (relates to point 1)? Can we state it as a [SMART](https://en.wikipedia.org/wiki/SMART_criteria) goal? +5. **Offer to help** (10 mins): What can we as your managers do better or differently to support you? +6. **Facilitator feedback** (5 mins): What are your feelings on this one-to-one? How should I improve as a facilitator? + +## Outcome + +The HR representative will summarize the outcome and new goals in a private mail with the employee. +The outcome of the meeting will be shared by discussion with the company governance, and potentially team leads if applicable. diff --git a/content/working-at-sparkfabrik/salaries.md b/content/working-at-sparkfabrik/salaries.md new file mode 100644 index 0000000..bea51f0 --- /dev/null +++ b/content/working-at-sparkfabrik/salaries.md @@ -0,0 +1,83 @@ +/* +Description: How we calculate salaries in SparkFabrik +Sort: 30 +*/ + +``` +NOTE: What follows has to be considered in "alpha stage". Actual values and policies will be tested and adjusted during year 2019. +Moreover, a way to reward horizontal growth (learning diversified skills) still have to be introduced. + +Despite that, this page is a sensible reference for our current salaries baselines and increases. +``` + +## Salary calculator + +Wages are calculated starting from [baseline salary brackets](#baseline-salary-brackets), sized by role. +On top of them we add: + +* **Lenght of service increments**: happens automatically as time passes by +* **Job interview scoring adjustments**: determined only at [hiring](/working-at-sparkfabrik/job-interviews) and affecting your starting wage +* **Impact scoring adjustments**: a running process related to your [professional growth](/working-at-sparkfabrik/career-advancement) + + +## Baseline salary brackets + +Here are the baseline brackets by role: + +| Role | Baseline salary (€) | +|---|---| +| Junior developer | 25K | +| Senior developer | 30K | +| Lead developer | 35K | +| Professional | 40K | +| Executive | 55K | + +Baseline brackets are tuned on an [Impact Score](/working-at-sparkfabrik/impact-scoring) of `2`, which represent nothing more, nor less than a perfect match between employee performance and company expectations. + +## Length of service increments + +When your length of service exceeds the following milestones your wage will automatically increase as listed: + +| Years of service | Salary increase (€) | +|---|---| +| 3 | 700 | +| 5 | 1.120 | +| 7 | 1.680 | +| 10 | 2.800 | + +## Job interview scoring adjustments + +During your job interview we will assess your proficiency and skills level so we can place you on the ladder. +Depending on your expectations, the interviewer perception and the overall [job interview score](/working-at-sparkfabrik/job-interviews) you will be assigned an _Impact-equivalent score_. + +A negative adjustment means we feel you can't match our expectations from the start, but we recognize key aspects of your personality that can fill the gap in the very first period of your career. +In this case we will take a chance on you, but also set clear goals for you so that: + +1. Your impact score meets the assessed level at the first check (1 to 3 months from hiring, depending on national contract employee level) +2. Your impact score raise to the average level within the second check (6 months of employment) + +If you score higher during your interview, or if you want to negotiate an initial wage higher than the baseline, you will need to match higher than average expectations: + +1. At the first check (1 to 3 months from hiring, depending on national contract employee level) your score will not be lower than **one step** below the level you negotiated for[1](#fn1) +2. We expect you to arrange a proper development plan to feel the possible gap with CTO and HR during your first 1-to-1 +3. Your impact score must to raise to the average level within the second check (8 months of employment) + +## Impact scoring adjustments + +As long as you repeatedly score above a certain threshold (3 times), you become eligible for a salary increase. +You may require a single score-supported salary increase during the same year that the company will honor without negotiation. + +If you aim to a higher salary for a specific year, you are encouraged to work towards that goal, working to increase the rating for your role's accountabilities or applying for a higher role, with more accountabilities for example. + +The following table represents the adjustements relative to impact scores, per role. To guarantee a fair and inclusive retribution to all company's workforce **these values are not negotiable**. + +| Impact Score | 1 | 1.25 | 1.5 | 1.75 | 2 | 2.25 | 2.5 | 2.75 | 3 | +|:---|---|---|---|---|---|---|---|---|---| +| **Junior Dev** | € 20.000 | € 21.250 | € 22.500 | € 23.750 | **€ 25.000** | € 25.900 | € 26.870 | € 27.770 | € 28.750 | +| **Senior Dev** | € 24.000 | € 25.500 | € 27.000 | € 28.500 | **€ 30.000** | € 31.150 | € 32.250 | € 33.350 | € 34.500 | +| **Lead Dev** | € 28.000 | € 29.750 | € 31.500 | € 33.250 | **€ 35.000** | € 36.300 | € 37.650 | € 38.900 | € 40.250 | +| **Professional** | € 32.000 | € 34.000 | € 36.000 | € 38.000 | **€ 40.000** | € 41.500 | € 43.000 | € 44.500 | € 46.000 | + +--- + +_1: For example, if you negotiated a salary of € 26.875 for a Junior position (corresponding to a score of 2.5), you must take a scorecard with a final score of at least 2.25 at your first 1 to 1 meeting. [↩](#fnr1)_ \ No newline at end of file diff --git a/content/working-at-sparkfabrik/sort b/content/working-at-sparkfabrik/sort new file mode 100644 index 0000000..9a03714 --- /dev/null +++ b/content/working-at-sparkfabrik/sort @@ -0,0 +1 @@ +10 \ No newline at end of file diff --git a/content/working-principles/sort b/content/working-principles/sort deleted file mode 100644 index 209e3ef..0000000 --- a/content/working-principles/sort +++ /dev/null @@ -1 +0,0 @@ -20 diff --git a/content/working-principles/tasks-and-time-tracking.md b/content/working-principles/tasks-and-time-tracking.md deleted file mode 100644 index 64ce1a9..0000000 --- a/content/working-principles/tasks-and-time-tracking.md +++ /dev/null @@ -1,34 +0,0 @@ -## Basic principles - -Working as a team, and loving order and focus, we want to keep track of all our tasks. -There are a bunch of reasons for this: - -1. Since our time on projects is charged to the customers, we want (!) them to know on what we spent our time -1. Having tracked tasks allow for project leaders, peers and customers to negotiate their priorities -1. We don't want ambiguity when we communicate: tracking tasks we can refer them with piercing precision using IDs -1. When a task is properly tracked and described, everybody in the team can work it out (trading off efficiency for efficacy maybe, but still) - -At the same extent, we want to track the time we spend on task so that: - -1. We can report it to client -1. We know if we are exceeding our budget or more basically how much we have spent -1. We can have metrics related to tasks life-cycles, etc. - -We **don't want** metrics about velocity or productivity of single persons! Everyone has her own pace. -Velocity rates are kept into consideration for the whole team, with the goal to continuously improve its effectiveness, remove obstacles, make them work less to produce more, etc. - -We appreciate people who sets personal goals on proficiency or productivity but we don't think it as a matter of sheer speed, so time is only one of the variables, not even the most important. Please, keep this in mind. - -### Tracking tasks - -We have [an instance of Redmine](https://projects.sparkfabrik.com) in place, with a bunch of nice additions to manage projects with agile methodologies and enforce our habits. - - @todo We also use Redmine to expose an issue tracker to the customers who pay support agreements, so they can open support tickets directly. We may be amending this practice or review it. Until then we'll skip this use case in this document. - -You must have credentials to log into our tracker and work on projects. What follows describes basic issue workflow and anatomy. Please find a list of useful recipes to perform basic-to-advanced tasks at the end of this chapter. - -#### Issue lifecycle - - - -## Tracking time diff --git a/custom/config.js b/custom/config.js index 3e9b82c..4641de9 100644 --- a/custom/config.js +++ b/custom/config.js @@ -1,10 +1,13 @@ 'use strict'; +// Modules +var path = require('path'); + var config = { // Your site title (format: page_title - site_title) - site_title: 'Sparkfabrik playbook', + site_title: 'SparkFabrik playbook', // The base URL of your site (can use %base_url% in Markdown files) base_url: '', @@ -13,7 +16,7 @@ var config = { support_email: '', // Footer Text / Copyright - copyright: 'Copyright © '+ new Date().getFullYear() +' - Powered by Raneto', + copyright: 'Copyright © ' + new Date().getFullYear() + ' - Powered by Raneto', // Excerpt length (used in search) excerpt_length: 400, @@ -26,17 +29,21 @@ var config = { // If true category folders need to contain a "sort" file with an integer value category_sort: true, + // Controls behavior of home page if meta ShowOnHome is not present. If set to true + // all categories or files that do not specify ShowOnHome meta property will be shown + show_on_home_default: true, + // Which Theme to Use? - theme_dir : __dirname + '/themes/', + theme_dir : path.join(__dirname, 'themes'), theme_name : 'spark', // Specify the path of your content folder where all your '.md' files are located // Fix: Needs trailing slash for now! // Fix: Cannot be an absolute path - content_dir : __dirname + '/content/', + content_dir : path.join(__dirname, 'content'), // Where is the public directory or document root? - public_dir : __dirname + '/assets/', + public_dir : path.join(__dirname, 'assets'), // The base URL of your images folder, // Relative to config.public_dir @@ -44,7 +51,7 @@ var config = { image_url: '/images', // Add your analytics tracking code (including script tags) - analytics: '', + analytics: '', // Set to true to enable the web editor allow_editing : false, @@ -52,16 +59,62 @@ var config = { // Set to true to enable HTTP Basic Authentication authentication : false, + // If editing is enabled, set this to true to only authenticate for editing, not for viewing + authentication_for_edit: true, + + // If authentication is enabled, set this to true to enable authentication for reading too + authentication_for_read: false, + + // Google OAuth + googleoauth: false, + oauth2 : { + client_id: 'GOOGLE_CLIENT_ID', + client_secret: 'GOOGLE_CLIENT_SECRET', + callback: 'http://localhost:3000/auth/google/callback', + hostedDomain: 'google.com' + }, + secret: 'someCoolSecretRightHere', + + credentials : [ + { + username : 'admin', + password : 'password' + }, + { + username : 'admin2', + password : 'password' + } + ], + locale: 'en', + // Support search with extra languages + searchExtraLanguages: ['it'], + + // Sets the format for datetime's + datetime_format: 'D MMM YYYY', + // Set to true to render suitable layout for RTL languages rtl_layout: false, // Edit Home Page title, description, etc. home_meta : { - //title : 'Custom Home Title', - //description : 'Custom Home Description' - } + title : 'SparkFabrik playbook', + description : 'All you - hopefully - need to know to work in and with SparkFabrik.' + }, + + // variables: [ + // { + // name: 'test_variable', + // content: 'test variable' + // }, + // { + // name: 'test_variable_2', + // content: 'test variable 2' + // } + // ] + + table_of_contents: false }; diff --git a/custom/custom-styles.css b/custom/custom-styles.css index f2ffbd8..0b76698 100644 --- a/custom/custom-styles.css +++ b/custom/custom-styles.css @@ -5,3 +5,8 @@ .content img { margin-left: 0; } + +.footer-content { + font-size: 0.925rem; + text-align: right; +} diff --git a/custom/templates/layout.html b/custom/templates/layout.html new file mode 100644 index 0000000..f390d1d --- /dev/null +++ b/custom/templates/layout.html @@ -0,0 +1,128 @@ + + + + + + + + + {{#meta.title}}{{meta.title}} - {{/meta.title}}{{config.site_title}} + {{#meta.description}}{{/meta.description}} + + + + + + + + + + {{#config.rtl_layout}} + + + {{/config.rtl_layout}} + {{{config.analytics}}} + + + +
+
+
+
+ +
+
+
+
+ + +
+
+ {{#config.authentication}} + + {{/config.authentication}} +
+
+
+
+ +
+ {{{yield}}} +
+ +
+
+
+

Cookie Policy

+ {{#config.copyright}} +

{{{config.copyright}}}

+ {{/config.copyright}} +
+
+
+ {{#config.allow_editing}} + {{#loggedIn}} + + + + + {{/loggedIn}} + {{/config.allow_editing}} + + + + + + + + + + diff --git a/custom/templates/page.html b/custom/templates/page.html new file mode 100644 index 0000000..fa32518 --- /dev/null +++ b/custom/templates/page.html @@ -0,0 +1,48 @@ +
+ +
+
+ {{#canEdit}} +
+ + +
+ {{/canEdit}} + {{#meta.title}}

{{meta.title}}

{{/meta.title}} + {{{content}}} +
+ {{#config.support_email}} +
+ {{lang.page.needHelp}} {{lang.page.getInTouch}} +
+ {{/config.support_email}} +
+ {{lang.global.lastUpdated}} {{last_modified}} +
+
+
+
+
diff --git a/docker-compose.yml b/docker-compose.yml index aa1adfd..a1cd472 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -7,3 +7,5 @@ documentation: - ./content:/srv/locke/content - ./custom/config.js:/srv/locke/config.js - ./custom/custom-styles.css:/srv/locke/themes/spark/public/styles/custom.css + - ./custom/templates/layout.html:/srv/locke/themes/spark/templates/layout.html + - ./custom/templates/page.html:/srv/locke/themes/spark/templates/page.html