DeveloperWiki:Parabolaweb

Parabolaweb is the software powering the main Parabola website. It is a fork of Archweb.

1 Installing

Most of the work of this has been automated by "parabolaweb-utils" package. Configure it with /etc/conf.d/parabolaweb. Then just run parabolaweb-update, and it will install parabolaweb at the configured location.

2 Workflow/Branches

Note: To configure the remotes such that this process makes sense, use the .git/config file below.

If you look at the git repository, you will see several branches. The flow is roughly:

archweb -> archweb-generic -> master-nomake -> master [ -> production]

This flow looks overly-complicated, but it makes merging changes from Archweb much easier.

The archweb branch is imported from Archweb's master branch, we make no changes to it.

The archweb-generic branch is a cleaned-up version of Archweb, it contains bugfixes, and makes parts of the branding configurable, something the Archweb developers have had in their TODO for a while (for example, all instances of "Arch Linux" should be replaced with "BRANDING_DISTRONAME"). All changes made in this branch should be things we think the Archweb developers should be willing to merge into their version.

The master-nomake branch is where the Parabola-specific things go. It is where most of the "development" happens. Part of this is that we have Makefiles to auto-generate files (that sometimes already exist from archweb), we DO NOT commit the re-generated versions of these files. Doing so clutters the diffs, and makes it difficult to see what changed.

The master is the same as master-nomake. The only difference is that the Makefile-generated files are committed. I do this by merging master-nomake, running make, git adding the changed files, the amending the merge commit to include them. I actually do this using git gui, so I can't tell you specific git commands to do this, off the top of my head.

2.1 Deploying to production

The .git/config file posted below configures a production branch that reflects what state the production server is in. Don't push directly to it, there is more to the deploy than just git (though, it could possibly be done as a post-push hook).

The process is pretty straight forward, just do this with the specified users on rshg054:

root# pacman -Sy parabolaweb-utils # update dependencies of parabolaweb
parabola$ parabolaweb-update
root# rc.d restart parabolaweb

The next time you fetch your local version, you will see the production branch changed to reflect this. You might notice that even though there are no differences between master and production, they have different commit objects. This is because at times, their histories have diverged. Ideally this wouldn't happen, but it did.

3 A useful .git/config

I have the following in my .git/config to make merging easy.

File: /srv/http/web/.git/config

[core]
	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true

[remote "origin"]
	fetch = +refs/heads/*:refs/remotes/origin/*
        url = https://projects.parabola.nu/parabolaweb.git
        pushUrl = ssh://git@projects.parabola.nu:1863/srv/git/parabolaweb.git
[branch "master"]
	remote = origin
	merge = refs/heads/master
[branch "master-nomake"]
	remote = origin
	merge = refs/heads/master-nomake
[branch "archweb-generic"]
	remote = origin
	merge = refs/heads/archweb-generic

[remote "prod"]
	fetch = +refs/heads/*:refs/remotes/prod/*
        url = ssh://parabola@parabola.nu:1863/srv/http/web/
[branch "production"]
        remote = prod
        merge = refs/heads/master

[remote "arch"]
	fetch = +refs/heads/*:refs/remotes/arch/*
	url = https://projects.archlinux.org/git/archweb.git
[branch "archweb"]
        remote = arch
        merge = refs/heads/master

I always merge a tag, or a specific commit. I use the commit message "Merge commit 7charactersOfHash (Summery of changes)"

4 Troubleshooting

4.1 HTTP 502 Bad Gateway from nginx

This means that parabolaweb is not running. Monit should automatically start parabolaweb if it notices that it's off. However, sometimes despite saying "[done]" when running "rc.d restart parabolaweb", it doesn't actually restart. Just run "rc.d start parabolaweb" to take care of that. That would not be a problem with systemd, process tracking is one thing that it really got right.