Skip to main content

Installation and Deployment

Open video on YouTube

Verify the archive SHA256 against an independently trusted reference before installation. On a mismatch or without a trusted reference, STOP: do not extract or run the installer.

Audience: the PM (project manager), IT administrators, and engineers who are installing the evaluation build themselves. For how to use isvn after installation, see the isvn User Guide.

0. Choose an installation method first

Method A: project installer Method B: Portable evaluation build
Who installs it The PM, once; members share it Each person, in their own home directory
Where it is installed The project directory chosen by the PM (<install dir>/bin) ~/.local/opt/isvn/<version>
Subversion Uses the svn already installed on the system The package ships its own svn, svnadmin and svnmucc
Qt (needed by the GUI) Not included; you specify the Qt path at install time Not included; it is linked to an existing Qt at install time
Initializes a project? Yes (runs isvn admin init) No; it only installs the programs
Purpose The team's real project Evaluation, tutorials and demo projects

Neither method needs root or sudo, and neither writes to system paths.

Figure I-01: The two installation methods compared.

Figure I-01. The two installation methods compared.


1. System overview

isvn stores the content of every version in SVN and, on top of that, provides version lineage, a deduplicating cache pool (the pool), and link-based workspaces. A deployment has three locations that can be placed separately, plus each member's own workspace:

Location Contents Size Recommendation
SVN repository The content of every version, accessed through file:// Large Mounted and expanded separately by IT
Pool The deduplicated content of working files Large Mounted and expanded separately by IT
Project directory Shared configuration and the lineage database (with Method A, the programs too) Small Under the PM's home directory is fine
Member workspaces The versions each member has checked out Depends on the workload Managed by each member
  • The three locations are independent of each other; they do not have to be under the same directory tree.
  • The capacity of the pool is determined by the mounted storage; isvn has no "set capacity" feature, and expanding capacity means adding storage.
  • tmp/ and objects/ in the pool must be on the same file system (writes use an atomic move). Putting the whole pool directory on one mount point is enough.

Figure I-03: The four locations of a deployment and how they relate.

Figure I-03. The four locations of a deployment and how they relate.


2. System requirements

Item Requirement
Operating system Linux x86_64. The Portable evaluation build needs glibc 2.34 or later; the target platforms are Ubuntu 24.04 and Rocky Linux 9
Subversion Method A: the system must have the svn client, plus svnadmin for creating the repository. Method B: not needed; the package ships its own
Qt Needed only by the GUI: Qt 6.7.3 (gcc_64). Qt is not included; it can be installed anywhere, but the install path and the lib/, plugins/ and qml/ inside it must not be writable by group or others
Graphical environment The GUI needs an X11 desktop environment and the system libraries required by Qt's xcb platform plugin
SQLite No separate installation needed; it is built into the programs
Project group One Linux group (for example prj_myproject); the PM and all members must belong to it
Permissions The PM must be able to create directories, set group permissions and create the SVN repository; root is not needed
Other python3 is used only by the TUT01 Demo Kit

3. Method A: project installer

3.1 Installer contents

isvn-installer/
  install.sh                  install script (run by the PM)
  README.md
  bin/
    isvn                      CLI
    isvn-gui                  GUI launcher (optional)
    libexec/isvn-gui          GUI main program (optional)
    libexec/isvn-gui.qt-version   Qt version the GUI was built with

The contents of bin/ come from the install tree of a Release build (cmake --install <build> --prefix <staging dir>).

Check before delivery: isvn-installer/bin/isvn in the source repository is only a placeholder used for testing the flow, and no GUI comes with it. When you build the installer, replace it with the CLI and GUI that were actually built.

3.2 Before you install

  1. Create the project group and add the PM and all members to it.

  2. Create the SVN repository (the install script does not create it for you):

    svnadmin create /data/svnrepos/myproject
    chgrp -R prj_myproject /data/svnrepos/myproject
    chmod -R g+rwX         /data/svnrepos/myproject
    
  3. If you are going to use the GUI, install Qt 6.7.3 first.

3.3 Run the installation

Interactive: follow the prompts to enter the install directory, repository, pool and group; when the installer includes the GUI, also enter the Qt path:

cd isvn-installer
./install.sh

Non-interactive:

./install.sh \
  --project-dir "$HOME/isvn/myproject" \
  --repo        file:///data/svnrepos/myproject \
  --pool        /cache/isvn_pool/myproject \
  --group       prj_myproject \
  --qt-prefix   /opt/Qt/6.7.3/gcc_64 \
  --yes
Parameter Description
--project-dir The install directory, which is also the project directory (ISVN_PROJECT_DIR). The programs and the environment files are installed here
--repo The file:// URL of the SVN repository; it must already exist and svn list must work on it
--pool The root directory of the pool
--group The name of the project's Linux group; it must already exist
--qt-prefix The Qt path used by the GUI. When it is omitted, the install script searches, in order, the environment variable ISVN_QT_PREFIX, qtpaths/qmake on PATH, CMAKE_PREFIX_PATH and common locations, and uses the first one it finds as the default
--yes Do not ask for confirmation item by item

3.4 What the install script does

  1. Checks that svn, the group and the repository are usable.
  2. Copies the CLI to <install dir>/bin/isvn. When the installer includes the GUI:
    • installs bin/isvn-gui and bin/libexec/isvn-gui;
    • after checking the version and permissions of Qt, creates bin/qt as a link to the Qt path.
  3. Generates <install dir>/isvn.cshrc and <install dir>/isvn.bashrc for members to source.
  4. Runs isvn admin init (see 3.5). This is skipped when the project has already been initialized.
  5. Prints the commands to give to the members.

Always start the GUI with isvn-gui; it finds Qt through bin/qt, so there is no need to set LD_LIBRARY_PATH.

3.5 What admin init does

isvn admin init \
  --project-dir "$HOME/isvn/myproject" \
  --repo        file:///data/svnrepos/myproject \
  --pool        /cache/isvn_pool/myproject \
  --group       prj_myproject
  • Creates the project directory and the .isvn/ inside it.
  • Creates the lineage database .isvn/lineage.db and records the top-level ROOT node.
  • Creates the pool structure: objects/, meta.db, locks/, tmp/, backup/.
  • Creates branches/ in the repository when it does not exist yet.
  • Writes .isvn/config (repository, pool, group).
  • Sets the group and permissions of the directories and files above explicitly, without relying on umask (see section 8 for the values).

On success it prints initialized isvn project at <project dir>.

Running it again is safe: when a ROOT record already exists it is not recorded a second time, and only the integrity of the lineage is checked. For what a re-run changes, see section 10. The account that runs admin init is the PM of this project.

3.6 Update the programs or change Qt

  • Project installer: Run install.sh again from the new installer with the same parameters. admin init is skipped for a project that is already initialized. To change Qt, just change --qt-prefix.
  • Environments managed with release slots (Production): Do not overwrite the programs by rerunning the install script; deploy as described in section 9.

4. Method B: Portable evaluation build

The Portable package shares one copy of Qt with Terminux; the package itself does not contain Qt.

4.1 Install

tar -xzf isvn-<version>-linux-x86_64.tar.gz
cd isvn-<version>-linux-x86_64
./install.sh --qt-dir /opt/Qt/6.7.3/gcc_64 --yes
  • --qt-dir is the root directory of Qt 6.7.3 gcc_64 (the directory that contains lib/libQt6Core.so.6). When it is omitted, the install script tries to reuse the Qt that Terminux uses.
  • It installs to ~/.local/opt/isvn/<version> and creates ~/.local/opt/isvn/current pointing to it.
  • The install script first verifies the files in the package (Package SHA256SUMS: OK), then checks Qt and the system libraries. The new version is set as current only after the Qt check passes.
  • When a check fails, it lists [FAIL] and the names of the missing libraries, and installs nothing.
  • When the same version is already installed, it reports already installed.
  • The install script does not modify PATH.

Actual output (a fresh account on Ubuntu 24.04, with Qt mounted at /opt/qt673):

Figure I-02: Real output of the Portable installation, isvn-preflight and isvn version.

Figure I-02. Real output of the Portable installation, isvn-preflight and isvn version.

4.2 Check

ISVN_HOME="$HOME/.local/opt/isvn/current"
"$ISVN_HOME/isvn-preflight"
"$ISVN_HOME/isvn" version

The installation is complete only when Ready. is the last line of the isvn-preflight output. WARN no DISPLAY only means that this terminal has no graphical environment; the CLI can still be used.

4.3 Use

  • Always start the programs through current/isvn, current/isvn-gui and the tools under current/svn/bin/. Running libexec/isvn directly bypasses the Subversion shipped in the package.
  • The GUI uses only the isvn in the same install directory.
  • The Portable evaluation build installs the programs only. There are two ways to get a project to work with:
    • create a demo project with the TUT01 Demo Kit (see the TUT01 Guide);

    • create a practice project and workspace yourself:

      ISVN_HOME="$HOME/.local/opt/isvn/current"
      mkdir -p "$HOME/isvn_trial"
      "$ISVN_HOME/svn/bin/svnadmin" create "$HOME/isvn_trial/svnrepo"
      "$ISVN_HOME/isvn" admin init \
        --project-dir "$HOME/isvn_trial/project" \
        --repo        "file://$HOME/isvn_trial/svnrepo" \
        --pool        "$HOME/isvn_trial/pool" \
        --group       "$(id -gn)"
      "$ISVN_HOME/isvn" member init \
        --project-dir "$HOME/isvn_trial/project" \
        --workspace   "$HOME/isvn_trial/work"
      

      $HOME/isvn_trial must be a directory name that does not exist yet. When this is done, create the first version as described in section 6.

Figure I-04 shows the result of actually running the same steps (to keep the commands shorter, current and current/svn/bin are added to PATH first); at the end it lists the directories and permissions created by admin init:

Figure I-04: Real output of creating a practice project, a workspace and the first version from scratch, with the permissions set by admin init.

Figure I-04. Real output of creating a practice project, a workspace and the first version from scratch, with the permissions set by admin init.


5. Members joining the project

Several accounts can use the same project, each in its own workspace. Each member joins by following the steps below.

Figure I-05: From installation to first use: once by the PM (top row), once by every member (bottom row).

Figure I-05. From installation to first use: once by the PM (top row), once by every member (bottom row).

5.1 Check the group

id -Gn          # the output must include the project group

An account that has just been added to the group must log in again before the change takes effect.

5.2 Set up the environment (Method A)

source the environment file provided by the PM that matches your shell; writing the command into ~/.cshrc or ~/.bashrc is recommended:

source <install dir>/isvn.cshrc   # tcsh/csh
source <install dir>/isvn.bashrc  # bash/sh

The environment file does only two things: it adds <install dir>/bin to PATH, and it sets ISVN_PROJECT_DIR. The locations of the repository and the pool come from .isvn/config; members do not need to set them.

5.3 Create the workspace

Each member runs this once:

isvn member init \
  --project-dir <project dir> \
  --workspace   "$HOME/work/myproject"

member init does the following:

  • reads the project's .isvn/config;
  • confirms that the current account belongs to the project group, and refuses otherwise;
  • confirms that the pool is usable (objects/, locks/ and meta.db all exist);
  • confirms that the repository can be reached;
  • creates the workspace directory and .isvn_local/, and records the location of the project directory.

On success it prints initialized isvn workspace at <workspace>.

The workspace root itself is not an SVN working copy; each version you check out afterwards goes into its own <workspace>/<phase>/<block>/<stage>/<version>/.

5.4 Get started

cd "$HOME/work/myproject"
isvn branches                               # list the versions in the repository
isvn checkout trial/cpu/200_fe_datain/v2    # check out one version
isvn-gui                                    # open the GUI

The GUI shows the Work page the first time it opens; when no version has been checked out yet, the screen looks like Figure U-06 (isvn User Guide, section 3.1).

Figure U-06: The GUI on first start: the Work page with no version in the workspace yet.

Figure U-06. The GUI on first start: the Work page with no version in the workspace yet.


6. Create the first version

A newly created repository has no versions, and the output of isvn branches is empty. For the first version you must state explicitly that it has no upstream:

cd <workspace>
isvn create trial/cpu/000_datain/v1 --parent ROOT

When it finishes it prints created trial/cpu/000_datain/v1 from ROOT, and the working copy of the new version is at <workspace>/trial/cpu/000_datain/v1/.

After you put the design files into this directory, commit them with batch check-in in the GUI or with isvn checkin-batch (see sections 9 and 19.1 of the isvn User Guide). Taking two files, top.v and constraints.sdc, as an example:

V=trial/cpu/000_datain/v1
plan_of() { python3 -c 'import json,sys; print(json.load(sys.stdin)["plan_hash"])'; }
plan=$(isvn checkin-batch preview $V --path top.v --path constraints.sdc --json | plan_of)
isvn checkin-batch apply $V --path top.v --path constraints.sdc --expected-plan "$plan" --message "initial design input" --json

"status":"committed" and revision in the output mean that the commit succeeded.

A single file or a whole folder can also be committed with isvn checkin <path> (see the isvn User Guide, section 19.2).


7. GC scheduling

GC is run from cron by the PM's account. Only the PM (the owner of the project's .isvn) can run isvn gc; other accounts are refused.

# hourly: remove stale link records and correct the reference counts (does not reclaim space)
0 * * * *  ISVN_PROJECT_DIR=/home/pm/isvn/myproject /home/pm/isvn/myproject/bin/isvn gc --reconcile

# daily: when usage exceeds 90%, reclaim space until it is below 70%
0 3 * * *  ISVN_PROJECT_DIR=/home/pm/isvn/myproject /home/pm/isvn/myproject/bin/isvn gc --reclaim --high 0.9 --low 0.7
  • cron does not carry over your usual environment, so write the full path of isvn and set ISVN_PROJECT_DIR. The paths above are examples; replace them with the actual install directory.
  • Before scheduling it for the first time, run isvn gc --reconcile --dry-run by hand to see what it would remove; it does not delete anything.
  • Reclaiming first deletes content that has no references at all. Only when that is still not enough does forced eviction remove the least recently used content; this means that the amount of data being worked on is close to the capacity of the pool, and it is a signal that the storage should be expanded. Use isvn pool-stat --evict-events to watch how often forced eviction happens.

SVN authz (optional): isvn does not manage SVN's path-based authz. If the team needs to divide read and write permissions by stage, configure that directly in SVN.


8. Directory layout and permissions

The permission values below are the modes that the install script and isvn create.

8.1 Project directory

<project dir>/                   2770
  bin/                           Method A only: isvn, isvn-gui, libexec/, qt
  isvn.cshrc, isvn.bashrc        Method A only: environment files for members (0644)
  .isvn/                         2770
    config                       0640   repository, pool, group
    lineage.db                   0660   lineage database

8.2 SVN repository

/data/svnrepos/myproject/
  branches/                      each version corresponds to branches/<phase>/<block>/<stage>/<version>

8.3 Pool

/cache/isvn_pool/myproject/      2770
  objects/                       3770
    <first two hash chars>/      3770
      <hash>                     0440   content object, read-only
  meta.db                        0660   records of objects and links
  locks/                         2770
  tmp/                           2770   temporary area for writes (must be on the same file system as objects/)
  backup/                        2770

8.4 Member workspace

<workspace>/                     0750
  .isvn_local/                   0700   private state of the workspace; do not edit by hand
    config                       0600   location of the project directory
    workspaces                   0600   list of checked-out versions
    workspace_state              0600   records of LOCAL files
    editable_receipts/                  Make Editable receipts (present only after use)
    work_operations/                    records of operations in progress (present only after use)
  <phase>/<block>/<stage>/<version>/    working copy of each version

8.5 Permission principles

  • The shared locations (project directory, pool) are all controlled through the project group plus explicit permissions, without relying on umask.
  • The content objects in the pool are read-only so that they are not modified by mistake; to modify a file you must use Make Editable on it first.
  • lineage.db is group-writable. The trustworthiness of the lineage does not rest on the file being read-only; it rests on append-only records, the account stored with each record, and the integrity check (isvn lineage verify).
  • The lineage database and the pool's meta.db are two separate files and must not be used interchangeably.

9. Production deployment and rollback (for maintainers)

The Production programs are not overwritten with the install script; they are managed with release slots:

Figure I-06: Release slots in production: deploying and rolling back both switch a link.

Figure I-06. Release slots in production: deploying and rolling back both switch a link.

  • <project dir>/bin is a link that points, through <project dir>/.isvn_release_slots/current, to the currently active slot (.isvn_release_slots/slots/<name>/). Each slot is one inseparable set of CLI and GUI, plus a file list and hashes (manifest.sha256, manifest.links).
  • Deployment first puts the new set into a new slot and then switches the link in one step; rollback switches back to an earlier slot.
  • Each slot carries its own qt link, which points to the Qt path specified at deployment time.
  • By default the newest 3 slots are kept as rollback targets.
# the source is the install tree of a Release build
cmake --install build-release --prefix build-release/stage

scripts/deploy_release.sh --dry-run                                   # rehearse first
scripts/deploy_release.sh --deploy [--qt-prefix /opt/Qt/6.7.3/gcc_64] # then deploy

scripts/rollback_release.sh --slot <slot name> --dry-run
scripts/rollback_release.sh --slot <slot name> --rollback

scripts/check_production_identity.sh                                  # verify the version and hashes of production

Rules:

  • Do not overwrite the production isvn or isvn-gui one by one with cp.
  • The CLI and the GUI are always deployed as a pair and rolled back as a pair.
  • When --qt-prefix is omitted, the Qt path of the current slot is reused.
  • Record every deployment and rollback in docs/deployment/DEPLOYMENT_LOG.md, and update docs/deployment/production_identity.env.

For the detailed steps, see docs/deployment/ROLLBACK_SOP.md and docs/deployment/PRODUCTION_IDENTITY_GUARD.md in the source repository.


10. Notes

  1. Re-running isvn admin init: Running it again with the same arguments is safe: it does not touch repository content, lineage records, pool content or members' workspaces. It does three things:

    • It sets the group of the project directory, .isvn and the pool root to --group and their mode back to 2770. If you changed the mode of those three directories yourself (for example, added the sticky bit), change it again afterwards.
    • It rewrites .isvn/config from the --repo, --pool and --group given this time. Anything added to that file by hand is not kept.
    • It creates branches/ in the repository if it is missing.

    Do not re-run it with a different --repo or --pool: the project would then point at another repository or pool, and existing workspaces are not moved.

  2. Permissions of the Qt path: If the Qt install path is writable by group or others, both the install script and the deployment script refuse it.


11. Verify the installation

11.1 PM

isvn version                 # confirm the build
isvn lineage verify          # should print Lineage integrity ok
isvn pool-stat               # new project: objects=0, refs=0
isvn admin status --json     # space and permission summary of the three locations

11.2 Members

cd <workspace>
isvn workspaces              # the first line is the project name; no other output when no version is checked out yet
isvn branches                # versions in the repository; empty for a new project

Running isvn status in the workspace root tells you to enter a version's directory first; this is normal.


12. Troubleshooting

Symptom Likely cause and what to do
member init: current user is not in project group The account has not been added to the project group. Ask the administrator to add it, log in again, then confirm with id -Gn
member init: pool is not initialized or not readable The pool is not mounted, or the permissions are wrong. Confirm that objects/, locks/ and meta.db all exist and that the group can access them
isvn: cannot locate project dir; set ISVN_PROJECT_DIR or run from a workspace You are not inside a workspace and ISVN_PROJECT_DIR is not set. source the environment file, or enter a workspace
isvn: not inside an isvn workspace; run isvn member init first This command must be run inside a workspace
The move fails when writing to the pool tmp/ and objects/ are not on the same file system. Put the whole pool on one mount point
isvn gc reports AUTHORIZATION_DENIED Only the PM can run GC
isvn remove <folder> reports svn: E155011 … is out of date A file in the folder has been committed again since the folder was checked out. Run isvn update in that version's directory first, then run the command again
The pool keeps growing and runs out of space The amount of data being worked on is larger than the capacity. Watch it with isvn pool-stat --evict-events; if forced eviction keeps occurring, arrange an expansion with IT
isvn lineage verify reports that the lineage is not intact Someone may have bypassed isvn and changed the database directly. Use isvn lineage audit to look at the accounts and times around the break point
GUI: refusing to start without its own isvn CLI The GUI's install directory has no matching isvn. Reinstall the complete set
The GUI cannot find the Qt libraries at startup bin/qt (or qt in the Portable build) does not point to the correct Qt 6.7.3. Method A: reinstall with --qt-prefix. Method B: reinstall with --qt-dir
install.sh of the Portable build: Qt check failed; nothing was installed The Qt path is wrong, or system libraries are missing. Fix what the [FAIL] line reports, then run it again