Devserver reference
Nasqueron Operations SIG maintains devservers. They offer a remote development environment for Nasqueron and open source projects.
General information
What server to use?
- WindRiver, for any general-purpose task
- Ysul, for webserver-legacy sites
- Dwellers, for Docker development
- Eglide, if you need an IRC session
How to get access?
You can ask it on DevCentral.
To speed up the process, you can follow NOG instructions at Operations grimoire/Create and revoke user accounts on Salt servers and send a commit to Differential against our operations repository.
| Server | Group name | Description |
|---|---|---|
| Ysul / WindRiver | nasquenautes | for general purpose development |
| Dwellers | dev-docker | for Docker development (group still to create) |
| Eglide | shell | for IRC purpose |
Userland
FreeBSD
Normally, devservers run under FreeBSD. That means your userland is a BSD one, and some commands arguments can be different if you're used to Linux. GNU coretools utilities are installed and prefixed by the letter g, e.g. gmake or gsed.
The most useful GNU commands are:
- gmake when the Makefile has been written for GNU make
- gsed -i to perform inline replacements
- gwatch (/usr/sbin/watch allows the user to examine all data coming through a specified tty, that's quite different)
Note grep is the BSD one, but documented to be GNU compatible.
Directories
- Use your /home/luser directory for anything personal
- Use /srv or /var when you need to share something, that generally requires a Salt config to give shared rights to that directory
- /var/51-wwwroot on Ysul is to use instead of your home folder for staging area of web applications you want to serve
- /datacube contains separate ZFS filesystems for a chunk of data, for example a backup, a collection of Git repositories, they can be declared in rOPS: pillar/devserver/datacubes.sls
tmux
- You can use
reptyr <pid>to attach a process spawned outside a tmux session in one - tmux cheat sheet
Mouse support
- nano allows to enable mouse mode with meta+m (ESC, m or alt + m)
- you can click on any character you want to navigate to
- if you initiate a selection with shift + up/down, you can extend it with the mouse
- in tmux, mouse mode (to configure, for example ctrl + b, m) allows you to resize panes
- mouse scroll (mouse wheel or swipe right of your touchpad) generally works like page up / page down to scroll in a buffer
FreeBSD development
For FreeBSD development tasks, WindRiver could be suitable if you need a amd64 arch. It's certainly suitable for ports development, as Poudriere is installed there.
Ports
Poudriere
The FreeBSD porter handbook suggests Poudriere as a convenient way to test ports in a clean environment.
One of the big interest of this method is to start from scratch, allowing to detect hidden dependencies, like pkg-config silently invoked by autotools.
Once time setup. Poudriere is installed in devserver role. To use it you need:
- a FreeBSD ports tree, let's say you clone it to /home/luser/dev/freebsd/ports - to declare `luser-dev: /home/luser/dev/freebsd/ports` to rOPS: pillar/devserver/ports.sls under poudriere.ports
Build a port. Then you can work in /home/luser/dev/freebsd/ports and build through:
sudo poudriere testport -j base14 -p luser_dev -o somecategory/someport
Logs. You can browse logs on the web, as https://windriver.nasqueron.org/poudriere serves /usr/local/poudriere/data/logs.
Cache. To speed up recompilation, ccache is used as disk cache. Metrics for the cache are available for WindRiver at http://172.27.27.35:2337/metrics/ccache (curl it from the server).
Databases
MariaDB
Works on server with the devserver-mysql role.
You've access to test_% databases, so you can without any specific configuration use that for unit tests. It's even OK to connect without login or password for the test_% namespace.
If you need any other database and app config, you can request it on DevCentral.
For long term projects, you can also specify where you want the credentials to be be provisioned, or request a Vault AppRole for your application to fetch them securely.
PostgreSQL
Works on server with the devserver-pgsql role.
Redis
For licensing purpose, should be replaced by Valkey. See this discussion on DevCentral for more context.
Redis is available on WindRiver, with database 0 used by NetBox.
General build information
Number of CPUS
On FreeBSD, the number of CPU core can be given by sysctl hw.ncpu while the full XML description is available at sysctl kern.sched.topology_spec.
Modern CPU allow for parallel compile tasks, use that.
For example, as of October 2024, you can use 12 core to build on WindRiver.
ccache
A compiler cache is installed with ccache.
The /etc/make.conf configuration file defines /var/cache/ccache directory to be used for ports build. That directory can't only be written as root.
You can create your own configuration in $HOME/.ccache/ccache.conf.
The exact path and configuration values can be get by ccache -s.
Rust
Rustup
If you wish to have control of what stable and nightly Rust versions to use, you can use Rustup.
To use it, the command rustup-init is available as an alternative to the curl magic documented on the Rustup web site (actually it's a fairly recent version of that script saved locally).
cargo, rustc
If you're OK with the Rust version installed by OS packages, feel free to call directly cargo or rustc.
Documentation
You can generate project documentation with the `cargo doc` command.
PHP
Tools provided
The following software are maintained as phar or repository clones in /opt:
- psysh, REPL shell to test PHP code (with PHP documentation available at /usr/local/share/psysh/php_manual.sqlite)
- psalm, for static analysis
- doctum and phpdoc (phpDocumentor) to generate documentation
- phpunit
- phpcs
Most of those tools have wrappers in /usr/local/bin trying to detect if a version is installed locally for the PHP project through Composer and switching to that version if available.
So by running "phpunit", you'll run your Composer version and the system version when missing.
Documentation
To generate documentation for your code, phpdoc and doctum commands are available, including GraphViz and PlantUML for phpDocumentor classes graphes.
Personal notes
You can add in this section links to your own personal notes to use the devserver for your activities, including ideally a disaster recovery plan (how do you reinstall the code your work with?)
Troubleshoot
You've lost a file
Your home directory has snapshots every 5 minutes, you can get back your recently lost file from a read-only snapshot:
cd ~/.zfs/snapshot ls
Those are folders with your home directory content as it was at the snapshot time, you can even diff files to spot differences:
cd zfs-auto-snap_hourly-2023-06-05-20h00 diff -u dev/nasqueron/operations/alkane/Jenkinsfile ~/dev/nasqueron/operations/alkane/Jenkinsfile
You've 12 months to act if your file is already in a monthly snapshot, but only 2 hours if it's in the last frequent snapshot and you keep modifying files, so act as quick as possible, ie right now. If you can't act right now, at least save the snapshot having the file (check that to avoid to save the wrong one) you want to recover with zfs hold:
zfs hold keep arcology/usr/home/dereckson@zfs-auto-snap_hourly-2023-06-05-22h00
SSH issues
If you've a message like username@windriver.nasqueron.org: Permission denied (publickey)., it can means:
- No SSH key has been offered
- SSH keys have been offered, but not recognized by the server
- Check rOPS: pillar/core/users.sls - do you have your public key on it?
- If not, and you have a new key, request to add your new SSH key
- SSH key is in a non-standard path - launch a SSH agent if needed (you've already one with your desktop engine), then ssh-add <path to key>
- SSH key is protected by a passphrase and you don't remember the password
- Solution 1. Try to remember the password, with an agent and ssh-add, it will be less confusing as you'll work locally
- Solution 2. Destroy the SSH key, create a new one, request to add that new key, login or ssh-add each day for one week to remember it
