chore: import upstream snapshot with attribution

api/.swaggo

@@ -0,0 +1 @@
+replace k8s.io/apimachinery/pkg/apis/meta/v1.Duration string

api/adminmonitor/admin_monitor.go

@@ -0,0 +1,116 @@
+package adminmonitor
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+	httperror "github.com/portainer/portainer/pkg/libhttp/error"
+
+	"github.com/rs/zerolog/log"
+)
+
+const RedirectReasonAdminInitTimeout string = "AdminInitTimeout"
+
+type Monitor struct {
+	timeout           time.Duration
+	datastore         dataservices.DataStore
+	cancellationFunc  context.CancelFunc
+	mu                sync.RWMutex
+	adminInitDisabled bool
+}
+
+// New creates a monitor that when started will wait for the timeout duration and then shutdown the application unless it has been initialized.
+func New(timeout time.Duration, datastore dataservices.DataStore) *Monitor {
+	return &Monitor{
+		timeout:           timeout,
+		datastore:         datastore,
+		adminInitDisabled: false,
+	}
+}
+
+// Start starts the monitor. The monitor will stop when ctx is cancelled, or when Stop is called.
+func (m *Monitor) Start(ctx context.Context) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	if m.cancellationFunc != nil {
+		return
+	}
+
+	cancellationCtx, cancellationFunc := context.WithCancel(ctx)
+	m.cancellationFunc = cancellationFunc
+
+	go func() {
+		log.Debug().Msg("start initialization monitor")
+
+		select {
+		case <-time.After(m.timeout):
+			initialized, err := m.WasInitialized()
+			if err != nil {
+				log.Error().Err(err).Msg("AdminMonitor failed to determine if Portainer is Initialized")
+				return
+			}
+
+			if !initialized {
+				log.Info().Msg("the Portainer instance timed out for security purposes, to re-enable your Portainer instance, you will need to restart Portainer")
+
+				m.mu.Lock()
+				defer m.mu.Unlock()
+
+				m.adminInitDisabled = true
+				return
+			}
+		case <-cancellationCtx.Done():
+			log.Debug().Msg("canceling initialization monitor")
+		}
+	}()
+}
+
+// Stop stops monitor. Safe to call even if monitor wasn't started.
+func (m *Monitor) Stop() {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	if m.cancellationFunc == nil {
+		return
+	}
+
+	m.cancellationFunc()
+	m.cancellationFunc = nil
+}
+
+// WasInitialized is a system initialization check
+func (m *Monitor) WasInitialized() (bool, error) {
+	users, err := m.datastore.User().UsersByRole(portainer.AdministratorRole)
+	if err != nil {
+		return false, err
+	}
+
+	return len(users) > 0, nil
+}
+
+func (m *Monitor) WasInstanceDisabled() bool {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	return m.adminInitDisabled
+}
+
+// WithRedirect checks whether administrator initialisation timeout. If so, it will return the error with redirect reason.
+// Otherwise, it will pass through the request to next
+func (m *Monitor) WithRedirect(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if m.WasInstanceDisabled() && strings.HasPrefix(r.RequestURI, "/api") && r.RequestURI != "/api/status" && r.RequestURI != "/api/settings/public" {
+			w.Header().Set("redirect-reason", RedirectReasonAdminInitTimeout)
+			httperror.WriteError(w, http.StatusSeeOther, "Administrator initialization timeout", nil)
+			return
+		}
+
+		next.ServeHTTP(w, r)
+	})
+}

api/adminmonitor/admin_monitor_test.go

@@ -0,0 +1,63 @@
+package adminmonitor
+
+import (
+	"testing"
+	"testing/synctest"
+	"time"
+
+	portainer "github.com/portainer/portainer/api"
+	i "github.com/portainer/portainer/api/internal/testhelpers"
+	"github.com/stretchr/testify/assert"
+)
+
+func Test_stopWithoutStarting(t *testing.T) {
+	t.Parallel()
+	monitor := New(1*time.Minute, nil)
+	monitor.Stop()
+}
+
+func Test_stopCouldBeCalledMultipleTimes(t *testing.T) {
+	t.Parallel()
+	monitor := New(1*time.Minute, nil)
+	monitor.Stop()
+	monitor.Stop()
+}
+
+func Test_startOrStopCouldBeCalledMultipleTimesConcurrently(t *testing.T) {
+	t.Parallel()
+	synctest.Test(t, test_startOrStopCouldBeCalledMultipleTimesConcurrently)
+}
+
+func test_startOrStopCouldBeCalledMultipleTimesConcurrently(t *testing.T) {
+	monitor := New(1*time.Minute, nil)
+
+	go monitor.Start(t.Context())
+	monitor.Start(t.Context())
+
+	go monitor.Stop()
+	monitor.Stop()
+
+	time.Sleep(2 * time.Second)
+}
+
+func Test_canStopStartedMonitor(t *testing.T) {
+	t.Parallel()
+	monitor := New(1*time.Minute, nil)
+	monitor.Start(t.Context())
+	assert.NotNil(t, monitor.cancellationFunc, "cancellation function is missing in started monitor")
+
+	monitor.Stop()
+	assert.Nil(t, monitor.cancellationFunc, "cancellation function should absent in stopped monitor")
+}
+
+func Test_start_shouldDisableInstanceAfterTimeout_ifNotInitialized(t *testing.T) {
+	t.Parallel()
+	timeout := 10 * time.Millisecond
+
+	datastore := i.NewDatastore(i.WithUsers([]portainer.User{}))
+	monitor := New(timeout, datastore)
+	monitor.Start(t.Context())
+
+	<-time.After(20 * timeout)
+	assert.True(t, monitor.WasInstanceDisabled(), "monitor should have been timeout and instance is disabled")
+}

api/agent/version.go

@@ -0,0 +1,80 @@
+package agent
+
+import (
+	"context"
+	"crypto/tls"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+	"time"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/url"
+	"github.com/portainer/portainer/pkg/libhttp/ssrf"
+
+	"github.com/rs/zerolog/log"
+)
+
+// GetAgentVersionAndPlatform returns the agent version and platform
+//
+// it sends a ping to the agent and parses the version and platform from the headers
+func GetAgentVersionAndPlatform(endpointUrl string, tlsConfig *tls.Config) (portainer.AgentPlatform, string, error) { //nolint:forbidigo
+	if err := ssrf.CheckURL(context.Background(), endpointUrl); err != nil {
+		return 0, "", err
+	}
+
+	httpCli := &http.Client{Timeout: 3 * time.Second}
+
+	if tlsConfig != nil {
+		httpCli.Transport = ssrf.NewTransport(tlsConfig)
+	}
+
+	parsedURL, err := url.ParseURL(endpointUrl + "/ping")
+	if err != nil {
+		return 0, "", err
+	}
+
+	parsedURL.Scheme = "https"
+
+	req, err := http.NewRequest(http.MethodGet, parsedURL.String(), nil)
+	if err != nil {
+		return 0, "", err
+	}
+
+	resp, err := httpCli.Do(req)
+	if err != nil {
+		return 0, "", err
+	}
+
+	_, _ = io.Copy(io.Discard, resp.Body)
+	if err := resp.Body.Close(); err != nil {
+		log.Warn().Err(err).Msg("failed to close response body")
+	}
+
+	if resp.StatusCode != http.StatusNoContent {
+		return 0, "", fmt.Errorf("Failed request with status %d", resp.StatusCode)
+	}
+
+	version := resp.Header.Get(portainer.PortainerAgentHeader)
+	if version == "" {
+		return 0, "", errors.New("Version Header is missing")
+	}
+
+	agentPlatformHeader := resp.Header.Get(portainer.HTTPResponseAgentPlatform)
+	if agentPlatformHeader == "" {
+		return 0, "", errors.New("Agent Platform Header is missing")
+	}
+
+	agentPlatformNumber, err := strconv.Atoi(agentPlatformHeader)
+	if err != nil {
+		return 0, "", err
+	}
+
+	if agentPlatformNumber == 0 {
+		return 0, "", errors.New("Agent platform is invalid")
+	}
+
+	return portainer.AgentPlatform(agentPlatformNumber), version, nil
+}

api/agent/version_test.go

@@ -0,0 +1,119 @@
+package agent
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"testing"
+
+	portainer "github.com/portainer/portainer/api"
+
+	"github.com/stretchr/testify/require"
+)
+
+func tlsServer(t *testing.T, handler http.HandlerFunc) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewTLSServer(handler)
+	t.Cleanup(srv.Close)
+
+	return srv
+}
+
+func TestGetAgentVersionAndPlatform_Success(t *testing.T) {
+	t.Parallel()
+
+	srv := tlsServer(t, func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set(portainer.PortainerAgentHeader, "2.19.0")
+		w.Header().Set(portainer.HTTPResponseAgentPlatform, "1")
+		w.WriteHeader(http.StatusNoContent)
+	})
+
+	tlsCfg := srv.Client().Transport.(*http.Transport).TLSClientConfig
+	platform, version, err := GetAgentVersionAndPlatform(srv.URL, tlsCfg)
+	require.NoError(t, err)
+	require.Equal(t, portainer.AgentPlatformDocker, platform)
+	require.Equal(t, "2.19.0", version)
+}
+
+func TestGetAgentVersionAndPlatform_NonOKStatus(t *testing.T) {
+	t.Parallel()
+
+	srv := tlsServer(t, func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized)
+	})
+
+	tlsCfg := srv.Client().Transport.(*http.Transport).TLSClientConfig
+	_, _, err := GetAgentVersionAndPlatform(srv.URL, tlsCfg)
+	require.Error(t, err)
+}
+
+func TestGetAgentVersionAndPlatform_MissingVersionHeader(t *testing.T) {
+	t.Parallel()
+
+	srv := tlsServer(t, func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set(portainer.HTTPResponseAgentPlatform, "1")
+		w.WriteHeader(http.StatusNoContent)
+	})
+
+	tlsCfg := srv.Client().Transport.(*http.Transport).TLSClientConfig
+	_, _, err := GetAgentVersionAndPlatform(srv.URL, tlsCfg)
+	require.Error(t, err)
+}
+
+func TestGetAgentVersionAndPlatform_MissingPlatformHeader(t *testing.T) {
+	t.Parallel()
+
+	srv := tlsServer(t, func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set(portainer.PortainerAgentHeader, "2.19.0")
+		w.WriteHeader(http.StatusNoContent)
+	})
+
+	tlsCfg := srv.Client().Transport.(*http.Transport).TLSClientConfig
+	_, _, err := GetAgentVersionAndPlatform(srv.URL, tlsCfg)
+	require.Error(t, err)
+}
+
+func TestGetAgentVersionAndPlatform_InvalidPlatformZero(t *testing.T) {
+	t.Parallel()
+
+	srv := tlsServer(t, func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set(portainer.PortainerAgentHeader, "2.19.0")
+		w.Header().Set(portainer.HTTPResponseAgentPlatform, "0")
+		w.WriteHeader(http.StatusNoContent)
+	})
+
+	tlsCfg := srv.Client().Transport.(*http.Transport).TLSClientConfig
+	_, _, err := GetAgentVersionAndPlatform(srv.URL, tlsCfg)
+	require.Error(t, err)
+}
+
+func TestGetAgentVersionAndPlatform_NonNumericPlatform(t *testing.T) {
+	t.Parallel()
+
+	srv := tlsServer(t, func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set(portainer.PortainerAgentHeader, "2.19.0")
+		w.Header().Set(portainer.HTTPResponseAgentPlatform, "docker")
+		w.WriteHeader(http.StatusNoContent)
+	})
+
+	tlsCfg := srv.Client().Transport.(*http.Transport).TLSClientConfig
+	_, _, err := GetAgentVersionAndPlatform(srv.URL, tlsCfg)
+	require.Error(t, err)
+}
+
+func TestGetAgentVersionAndPlatform_PingPathAppended(t *testing.T) {
+	t.Parallel()
+
+	var gotPath string
+	srv := tlsServer(t, func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		w.Header().Set(portainer.PortainerAgentHeader, "2.19.0")
+		w.Header().Set(portainer.HTTPResponseAgentPlatform, strconv.Itoa(int(portainer.AgentPlatformKubernetes)))
+		w.WriteHeader(http.StatusNoContent)
+	})
+
+	tlsCfg := srv.Client().Transport.(*http.Transport).TLSClientConfig
+	_, _, err := GetAgentVersionAndPlatform(srv.URL, tlsCfg)
+	require.NoError(t, err)
+	require.Equal(t, "/ping", gotPath)
+}

api/api.md

@@ -0,0 +1,61 @@
+The Portainer API is an HTTP API served by Portainer. It is used by the Portainer UI, and anything you can do in the UI can also be done via the HTTP API.
+
+API examples are available in the [Portainer documentation](https://documentation.portainer.io/api/api-examples/)
+
+You can find out more about Portainer [on our website](http://portainer.io) and get some support on [Slack](http://portainer.io/slack/).
+
+# Authentication
+
+Most of the API endpoints require authentication, as well as some level of authorization.
+Portainer uses JSON Web Tokens to manage authentication. You must provide a token in the **Authorization** header of each request using the **Bearer** scheme.
+
+Example:
+
+```
+Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE
+```
+
+# Security
+
+Each API endpoint has an associated access policy, documented in its description.
+
+The following policies are available:
+
+- Public access
+- Authenticated access
+- Restricted access
+- Administrator access
+
+### Public access
+
+No authentication is required.
+
+### Authenticated access
+
+Authentication is required.
+
+### Restricted access
+
+Authentication is required. Additional checks may apply to verify access to the resource, and returned data may be filtered.
+
+### Administrator access
+
+Authentication and an administrator role are both required.
+
+# Execute Docker requests
+
+Portainer does not expose dedicated endpoints for managing Docker resources (create a container, remove a volume, etc).
+
+Instead, it acts as a reverse-proxy to the Docker HTTP API, allowing you to execute Docker requests via the Portainer HTTP API.
+
+To do so, use the `/endpoints/{id}/docker` endpoint. Note that this endpoint is not documented below due to Swagger limitations. It has a restricted access policy, so authentication is still required. Any request made to this endpoint is proxied to the Docker API of the associated environment - request and response objects are identical to those in the [Docker official documentation](https://docs.docker.com/engine/api).
+
+# Private Registry
+
+When using a private registry, include a Base64-encoded JSON string in the request header. The header parameter name is `X-Registry-Auth` and the value should encode the following structure: ‘{"registryId":\<registryId\>}’ where `<registryId>` is the ID of the registry where the repository was created.
+
+Example encoded value:
+
+```
+eyJyZWdpc3RyeUlkIjoxfQ==
+```

api/apikey/apikey.go

@@ -0,0 +1,17 @@
+package apikey
+
+import (
+	portainer "github.com/portainer/portainer/api"
+)
+
+// APIKeyService represents a service for managing API keys.
+type APIKeyService interface {
+	HashRaw(rawKey string) string
+	GenerateApiKey(user portainer.User, description string) (string, *portainer.APIKey, error)
+	GetAPIKey(apiKeyID portainer.APIKeyID) (*portainer.APIKey, error)
+	GetAPIKeys(userID portainer.UserID) ([]portainer.APIKey, error)
+	GetDigestUserAndKey(digest string) (portainer.User, portainer.APIKey, error)
+	UpdateAPIKey(apiKey *portainer.APIKey) error
+	DeleteAPIKey(apiKeyID portainer.APIKeyID) error
+	InvalidateUserKeyCache(userId portainer.UserID) bool
+}

api/apikey/apikey_test.go

@@ -0,0 +1,53 @@
+package apikey
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func Test_generateRandomKey(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	tests := []struct {
+		name       string
+		wantLength int
+	}{
+		{
+			name:       "Generate a random key of length 16",
+			wantLength: 16,
+		},
+		{
+			name:       "Generate a random key of length 32",
+			wantLength: 32,
+		},
+		{
+			name:       "Generate a random key of length 64",
+			wantLength: 64,
+		},
+		{
+			name:       "Generate a random key of length 128",
+			wantLength: 128,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := GenerateRandomKey(tt.wantLength)
+			is.Len(got, tt.wantLength)
+		})
+	}
+
+	t.Run("Generated keys are unique", func(t *testing.T) {
+		keys := make(map[string]bool)
+
+		for range 100 {
+			key := GenerateRandomKey(8)
+			_, ok := keys[string(key)]
+			is.False(ok)
+
+			keys[string(key)] = true
+		}
+	})
+}

api/apikey/cache.go

@@ -0,0 +1,79 @@
+package apikey
+
+import (
+	portainer "github.com/portainer/portainer/api"
+
+	lru "github.com/hashicorp/golang-lru"
+)
+
+const DefaultAPIKeyCacheSize = 1024
+
+// entry is a tuple containing the user and API key associated to an API key digest
+type entry[T any] struct {
+	user   T
+	apiKey portainer.APIKey
+}
+
+type UserCompareFn[T any] func(T, portainer.UserID) bool
+
+// ApiKeyCache is a concurrency-safe, in-memory cache which primarily exists for to reduce database roundtrips.
+// We store the api-key digest (keys) and the associated user and key-data (values) in the cache.
+// This is required because HTTP requests will contain only the api-key digest in the x-api-key request header;
+// digest value must be mapped to a portainer user (and respective key data) for validation.
+// This cache is used to avoid multiple database queries to retrieve these user/key associated to the digest.
+type ApiKeyCache[T any] struct {
+	// cache type [string]entry cache (key: string(digest), value: user/key entry)
+	// note: []byte keys are not supported by golang-lru Cache
+	cache     *lru.Cache
+	userCmpFn UserCompareFn[T]
+}
+
+// NewAPIKeyCache creates a new cache for API keys
+func NewAPIKeyCache[T any](cacheSize int, userCompareFn UserCompareFn[T]) *ApiKeyCache[T] {
+	cache, _ := lru.New(cacheSize)
+
+	return &ApiKeyCache[T]{cache: cache, userCmpFn: userCompareFn}
+}
+
+// Get returns the user/key associated to an api-key's digest
+// This is required because HTTP requests will contain the digest of the API key in header,
+// the digest value must be mapped to a portainer user.
+func (c *ApiKeyCache[T]) Get(digest string) (T, portainer.APIKey, bool) {
+	val, ok := c.cache.Get(digest)
+	if !ok {
+		var t T
+
+		return t, portainer.APIKey{}, false
+	}
+
+	tuple := val.(entry[T])
+
+	return tuple.user, tuple.apiKey, true
+}
+
+// Set persists a user/key entry to the cache
+func (c *ApiKeyCache[T]) Set(digest string, user T, apiKey portainer.APIKey) {
+	c.cache.Add(digest, entry[T]{
+		user:   user,
+		apiKey: apiKey,
+	})
+}
+
+// Delete evicts a digest's user/key entry key from the cache
+func (c *ApiKeyCache[T]) Delete(digest string) {
+	c.cache.Remove(digest)
+}
+
+// InvalidateUserKeyCache loops through all the api-keys associated to a user and removes them from the cache
+func (c *ApiKeyCache[T]) InvalidateUserKeyCache(userId portainer.UserID) bool {
+	present := false
+
+	for _, k := range c.cache.Keys() {
+		user, _, _ := c.Get(k.(string))
+		if c.userCmpFn(user, userId) {
+			present = c.cache.Remove(k) || present
+		}
+	}
+
+	return present
+}

api/apikey/cache_test.go

@@ -0,0 +1,186 @@
+package apikey
+
+import (
+	"testing"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/stretchr/testify/assert"
+)
+
+func Test_apiKeyCacheGet(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	keyCache := NewAPIKeyCache(10, compareUser)
+
+	// pre-populate cache
+	keyCache.cache.Add(string("foo"), entry[portainer.User]{user: portainer.User{}, apiKey: portainer.APIKey{}})
+	keyCache.cache.Add(string(""), entry[portainer.User]{user: portainer.User{}, apiKey: portainer.APIKey{}})
+
+	tests := []struct {
+		digest string
+		found  bool
+	}{
+		{
+			digest: "foo",
+			found:  true,
+		},
+		{
+			digest: "",
+			found:  true,
+		},
+		{
+			digest: "bar",
+			found:  false,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.digest, func(t *testing.T) {
+			_, _, found := keyCache.Get(test.digest)
+			is.Equal(test.found, found)
+		})
+	}
+}
+
+func Test_apiKeyCacheSet(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	keyCache := NewAPIKeyCache(10, compareUser)
+
+	// pre-populate cache
+	keyCache.Set("bar", portainer.User{ID: 2}, portainer.APIKey{})
+	keyCache.Set("foo", portainer.User{ID: 1}, portainer.APIKey{})
+
+	// overwrite existing entry
+	keyCache.Set("foo", portainer.User{ID: 3}, portainer.APIKey{})
+
+	val, ok := keyCache.cache.Get(string("bar"))
+	is.True(ok)
+
+	tuple := val.(entry[portainer.User])
+	is.Equal(portainer.User{ID: 2}, tuple.user)
+
+	val, ok = keyCache.cache.Get(string("foo"))
+	is.True(ok)
+
+	tuple = val.(entry[portainer.User])
+	is.Equal(portainer.User{ID: 3}, tuple.user)
+}
+
+func Test_apiKeyCacheDelete(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	keyCache := NewAPIKeyCache(10, compareUser)
+
+	t.Run("Delete an existing entry", func(t *testing.T) {
+		keyCache.cache.Add(string("foo"), entry[portainer.User]{user: portainer.User{ID: 1}, apiKey: portainer.APIKey{}})
+		keyCache.Delete("foo")
+
+		_, ok := keyCache.cache.Get(string("foo"))
+		is.False(ok)
+	})
+
+	t.Run("Delete a non-existing entry", func(t *testing.T) {
+		nonPanicFunc := func() { keyCache.Delete("non-existent-key") }
+		is.NotPanics(nonPanicFunc)
+	})
+}
+
+func Test_apiKeyCacheLRU(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	tests := []struct {
+		name        string
+		cacheLen    int
+		key         []string
+		foundKeys   []string
+		evictedKeys []string
+	}{
+		{
+			name:        "Cache length is 1, add 2 keys",
+			cacheLen:    1,
+			key:         []string{"foo", "bar"},
+			foundKeys:   []string{"bar"},
+			evictedKeys: []string{"foo"},
+		},
+		{
+			name:        "Cache length is 1, add 3 keys",
+			cacheLen:    1,
+			key:         []string{"foo", "bar", "baz"},
+			foundKeys:   []string{"baz"},
+			evictedKeys: []string{"foo", "bar"},
+		},
+		{
+			name:        "Cache length is 2, add 3 keys",
+			cacheLen:    2,
+			key:         []string{"foo", "bar", "baz"},
+			foundKeys:   []string{"bar", "baz"},
+			evictedKeys: []string{"foo"},
+		},
+		{
+			name:        "Cache length is 2, add 4 keys",
+			cacheLen:    2,
+			key:         []string{"foo", "bar", "baz", "qux"},
+			foundKeys:   []string{"baz", "qux"},
+			evictedKeys: []string{"foo", "bar"},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			keyCache := NewAPIKeyCache(test.cacheLen, compareUser)
+
+			for _, key := range test.key {
+				keyCache.Set(key, portainer.User{ID: 1}, portainer.APIKey{})
+			}
+
+			for _, key := range test.foundKeys {
+				_, _, found := keyCache.Get(key)
+				is.True(found, "Key %s not found", key)
+			}
+
+			for _, key := range test.evictedKeys {
+				_, _, found := keyCache.Get(key)
+				is.False(found, "key %s should have been evicted", key)
+			}
+		})
+	}
+}
+
+func Test_apiKeyCacheInvalidateUserKeyCache(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	keyCache := NewAPIKeyCache(10, compareUser)
+
+	t.Run("Removes users keys from cache", func(t *testing.T) {
+		keyCache.cache.Add(string("foo"), entry[portainer.User]{user: portainer.User{ID: 1}, apiKey: portainer.APIKey{}})
+
+		ok := keyCache.InvalidateUserKeyCache(1)
+		is.True(ok)
+
+		_, ok = keyCache.cache.Get(string("foo"))
+		is.False(ok)
+	})
+
+	t.Run("Does not affect other keys", func(t *testing.T) {
+		keyCache.cache.Add(string("foo"), entry[portainer.User]{user: portainer.User{ID: 1}, apiKey: portainer.APIKey{}})
+		keyCache.cache.Add(string("bar"), entry[portainer.User]{user: portainer.User{ID: 2}, apiKey: portainer.APIKey{}})
+
+		ok := keyCache.InvalidateUserKeyCache(1)
+		is.True(ok)
+
+		ok = keyCache.InvalidateUserKeyCache(1)
+		is.False(ok)
+
+		_, ok = keyCache.cache.Get(string("foo"))
+		is.False(ok)
+
+		_, ok = keyCache.cache.Get(string("bar"))
+		is.True(ok)
+	})
+}

api/apikey/service.go

@@ -0,0 +1,143 @@
+package apikey
+
+import (
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"fmt"
+	"io"
+	"time"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+
+	"github.com/pkg/errors"
+)
+
+const portainerAPIKeyPrefix = "ptr_"
+
+var ErrInvalidAPIKey = errors.New("Invalid API key")
+
+type apiKeyService struct {
+	apiKeyRepository dataservices.APIKeyRepository
+	userRepository   dataservices.UserService
+	cache            *ApiKeyCache[portainer.User]
+}
+
+// GenerateRandomKey generates a random key of specified length
+// source: https://github.com/gorilla/securecookie/blob/master/securecookie.go#L515
+func GenerateRandomKey(length int) []byte {
+	k := make([]byte, length)
+	if _, err := io.ReadFull(rand.Reader, k); err != nil {
+		return nil
+	}
+
+	return k
+}
+
+func compareUser(u portainer.User, id portainer.UserID) bool {
+	return u.ID == id
+}
+
+func NewAPIKeyService(apiKeyRepository dataservices.APIKeyRepository, userRepository dataservices.UserService) *apiKeyService {
+	return &apiKeyService{
+		apiKeyRepository: apiKeyRepository,
+		userRepository:   userRepository,
+		cache:            NewAPIKeyCache(DefaultAPIKeyCacheSize, compareUser),
+	}
+}
+
+// HashRaw computes a hash digest of provided raw API key.
+func (a *apiKeyService) HashRaw(rawKey string) string {
+	hashDigest := sha256.Sum256([]byte(rawKey))
+
+	return base64.StdEncoding.EncodeToString(hashDigest[:])
+}
+
+// GenerateApiKey generates a raw API key for a user (for one-time display).
+// The generated API key is stored in the cache and database.
+func (a *apiKeyService) GenerateApiKey(user portainer.User, description string) (string, *portainer.APIKey, error) {
+	randKey := GenerateRandomKey(32)
+	encodedRawAPIKey := base64.StdEncoding.EncodeToString(randKey)
+	prefixedAPIKey := portainerAPIKeyPrefix + encodedRawAPIKey
+	hashDigest := a.HashRaw(prefixedAPIKey)
+
+	apiKey := &portainer.APIKey{
+		UserID:      user.ID,
+		Description: description,
+		Prefix:      prefixedAPIKey[:7],
+		DateCreated: time.Now().Unix(),
+		Digest:      hashDigest,
+	}
+
+	if err := a.apiKeyRepository.Create(apiKey); err != nil {
+		return "", nil, errors.Wrap(err, "Unable to create API key")
+	}
+
+	// persist api-key to cache
+	a.cache.Set(apiKey.Digest, user, *apiKey)
+
+	return prefixedAPIKey, apiKey, nil
+}
+
+// GetAPIKey returns an API key by its ID.
+func (a *apiKeyService) GetAPIKey(apiKeyID portainer.APIKeyID) (*portainer.APIKey, error) {
+	return a.apiKeyRepository.Read(apiKeyID)
+}
+
+// GetAPIKeys returns all the API keys associated to a user.
+func (a *apiKeyService) GetAPIKeys(userID portainer.UserID) ([]portainer.APIKey, error) {
+	return a.apiKeyRepository.GetAPIKeysByUserID(userID)
+}
+
+// GetDigestUserAndKey returns the user and api-key associated to a specified hash digest.
+// A cache lookup is performed first; if the user/api-key is not found in the cache, respective database lookups are performed.
+func (a *apiKeyService) GetDigestUserAndKey(digest string) (portainer.User, portainer.APIKey, error) {
+	cachedUser, cachedKey, ok := a.cache.Get(digest)
+	if ok {
+		return cachedUser, cachedKey, nil
+	}
+
+	apiKey, err := a.apiKeyRepository.GetAPIKeyByDigest(digest)
+	if err != nil {
+		return portainer.User{}, portainer.APIKey{}, errors.Wrap(err, "Unable to retrieve API key")
+	}
+
+	user, err := a.userRepository.Read(apiKey.UserID)
+	if err != nil {
+		return portainer.User{}, portainer.APIKey{}, errors.Wrap(err, "Unable to retrieve digest user")
+	}
+
+	// persist api-key to cache - for quicker future lookups
+	a.cache.Set(apiKey.Digest, *user, *apiKey)
+
+	return *user, *apiKey, nil
+}
+
+// UpdateAPIKey updates an API key and in cache and database.
+func (a *apiKeyService) UpdateAPIKey(apiKey *portainer.APIKey) error {
+	user, _, err := a.GetDigestUserAndKey(apiKey.Digest)
+	if err != nil {
+		return errors.Wrap(err, "Unable to retrieve API key")
+	}
+
+	a.cache.Set(apiKey.Digest, user, *apiKey)
+
+	return a.apiKeyRepository.Update(apiKey.ID, apiKey)
+}
+
+// DeleteAPIKey deletes an API key and removes the digest/api-key entry from the cache.
+func (a *apiKeyService) DeleteAPIKey(apiKeyID portainer.APIKeyID) error {
+	apiKey, err := a.apiKeyRepository.Read(apiKeyID)
+	if err != nil {
+		return errors.Wrap(err, fmt.Sprintf("Unable to retrieve API key: %d", apiKeyID))
+	}
+
+	a.cache.Delete(apiKey.Digest)
+
+	return a.apiKeyRepository.Delete(apiKeyID)
+}
+
+func (a *apiKeyService) InvalidateUserKeyCache(userId portainer.UserID) bool {
+	return a.cache.InvalidateUserKeyCache(userId)
+}

api/apikey/service_test.go

@@ -0,0 +1,315 @@
+package apikey
+
+import (
+	"crypto/sha256"
+	"encoding/base64"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/datastore"
+
+	"github.com/rs/zerolog/log"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_SatisfiesAPIKeyServiceInterface(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+	is.Implements((*APIKeyService)(nil), NewAPIKeyService(nil, nil))
+}
+
+func Test_GenerateApiKey(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	_, store := datastore.MustNewTestStore(t, true, true)
+
+	service := NewAPIKeyService(store.APIKeyRepository(), store.User())
+
+	t.Run("Successfully generates API key", func(t *testing.T) {
+		desc := "test-1"
+		rawKey, apiKey, err := service.GenerateApiKey(portainer.User{ID: 1}, desc)
+		require.NoError(t, err)
+		is.NotEmpty(rawKey)
+		is.NotEmpty(apiKey)
+		is.Equal(desc, apiKey.Description)
+	})
+
+	t.Run("Api key prefix is 7 chars", func(t *testing.T) {
+		rawKey, apiKey, err := service.GenerateApiKey(portainer.User{ID: 1}, "test-2")
+		require.NoError(t, err)
+
+		is.Equal(rawKey[:7], apiKey.Prefix)
+		is.Len(apiKey.Prefix, 7)
+	})
+
+	t.Run("Api key has 'ptr_' as prefix", func(t *testing.T) {
+		rawKey, _, err := service.GenerateApiKey(portainer.User{ID: 1}, "test-x")
+		require.NoError(t, err)
+
+		is.Equal(portainerAPIKeyPrefix, "ptr_")
+		is.True(strings.HasPrefix(rawKey, "ptr_"))
+	})
+
+	t.Run("Successfully caches API key", func(t *testing.T) {
+		user := portainer.User{ID: 1}
+		_, apiKey, err := service.GenerateApiKey(user, "test-3")
+		require.NoError(t, err)
+
+		userFromCache, apiKeyFromCache, ok := service.cache.Get(apiKey.Digest)
+		is.True(ok)
+		is.Equal(user, userFromCache)
+		is.Equal(apiKey, &apiKeyFromCache)
+	})
+
+	t.Run("Decoded raw api-key digest matches generated digest", func(t *testing.T) {
+		rawKey, apiKey, err := service.GenerateApiKey(portainer.User{ID: 1}, "test-4")
+		require.NoError(t, err)
+
+		generatedDigest := sha256.Sum256([]byte(rawKey))
+
+		is.Equal(apiKey.Digest, base64.StdEncoding.EncodeToString(generatedDigest[:]))
+	})
+}
+
+func Test_GetAPIKey(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	_, store := datastore.MustNewTestStore(t, true, true)
+
+	service := NewAPIKeyService(store.APIKeyRepository(), store.User())
+
+	t.Run("Successfully returns all API keys", func(t *testing.T) {
+		user := portainer.User{ID: 1}
+		_, apiKey, err := service.GenerateApiKey(user, "test-1")
+		require.NoError(t, err)
+
+		apiKeyGot, err := service.GetAPIKey(apiKey.ID)
+		require.NoError(t, err)
+
+		is.Equal(apiKey, apiKeyGot)
+	})
+}
+
+func Test_GetAPIKeys(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	_, store := datastore.MustNewTestStore(t, true, true)
+
+	service := NewAPIKeyService(store.APIKeyRepository(), store.User())
+
+	t.Run("Successfully returns all API keys", func(t *testing.T) {
+		user := portainer.User{ID: 1}
+		_, _, err := service.GenerateApiKey(user, "test-1")
+		require.NoError(t, err)
+		_, _, err = service.GenerateApiKey(user, "test-2")
+		require.NoError(t, err)
+
+		keys, err := service.GetAPIKeys(user.ID)
+		require.NoError(t, err)
+		is.Len(keys, 2)
+	})
+}
+
+func Test_GetDigestUserAndKey(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	_, store := datastore.MustNewTestStore(t, true, true)
+
+	service := NewAPIKeyService(store.APIKeyRepository(), store.User())
+
+	t.Run("Successfully returns user and api key associated to digest", func(t *testing.T) {
+		user := portainer.User{ID: 1}
+		_, apiKey, err := service.GenerateApiKey(user, "test-1")
+		require.NoError(t, err)
+
+		userGot, apiKeyGot, err := service.GetDigestUserAndKey(apiKey.Digest)
+		require.NoError(t, err)
+		is.Equal(user, userGot)
+		is.Equal(*apiKey, apiKeyGot)
+	})
+
+	t.Run("Successfully caches user and api key associated to digest", func(t *testing.T) {
+		user := portainer.User{ID: 1}
+		_, apiKey, err := service.GenerateApiKey(user, "test-1")
+		require.NoError(t, err)
+
+		userGot, apiKeyGot, err := service.GetDigestUserAndKey(apiKey.Digest)
+		require.NoError(t, err)
+		is.Equal(user, userGot)
+		is.Equal(*apiKey, apiKeyGot)
+
+		userFromCache, apiKeyFromCache, ok := service.cache.Get(apiKey.Digest)
+		is.True(ok)
+		is.Equal(userGot, userFromCache)
+		is.Equal(apiKeyGot, apiKeyFromCache)
+	})
+}
+
+func Test_UpdateAPIKey(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	_, store := datastore.MustNewTestStore(t, true, true)
+
+	service := NewAPIKeyService(store.APIKeyRepository(), store.User())
+
+	t.Run("Successfully updates the api-key LastUsed time", func(t *testing.T) {
+		user := portainer.User{ID: 1}
+
+		err := store.User().Create(&user)
+		require.NoError(t, err)
+
+		_, apiKey, err := service.GenerateApiKey(user, "test-x")
+		require.NoError(t, err)
+
+		apiKey.LastUsed = time.Now().UTC().Unix()
+		err = service.UpdateAPIKey(apiKey)
+		require.NoError(t, err)
+
+		_, apiKeyGot, err := service.GetDigestUserAndKey(apiKey.Digest)
+		require.NoError(t, err)
+
+		log.Debug().Str("wanted", fmt.Sprintf("%+v", apiKey)).Str("got", fmt.Sprintf("%+v", apiKeyGot)).Msg("")
+
+		is.Equal(apiKey.LastUsed, apiKeyGot.LastUsed)
+	})
+
+	t.Run("Successfully updates api-key in cache upon api-key update", func(t *testing.T) {
+		_, apiKey, err := service.GenerateApiKey(portainer.User{ID: 1}, "test-x2")
+		require.NoError(t, err)
+
+		_, apiKeyFromCache, ok := service.cache.Get(apiKey.Digest)
+		is.True(ok)
+		is.Equal(*apiKey, apiKeyFromCache)
+
+		apiKey.LastUsed = time.Now().UTC().Unix()
+		is.NotEqual(*apiKey, apiKeyFromCache)
+
+		err = service.UpdateAPIKey(apiKey)
+		require.NoError(t, err)
+
+		_, updatedAPIKeyFromCache, ok := service.cache.Get(apiKey.Digest)
+		is.True(ok)
+		is.Equal(*apiKey, updatedAPIKeyFromCache)
+	})
+}
+
+func Test_DeleteAPIKey(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	_, store := datastore.MustNewTestStore(t, true, true)
+
+	service := NewAPIKeyService(store.APIKeyRepository(), store.User())
+
+	t.Run("Successfully updates the api-key", func(t *testing.T) {
+		user := portainer.User{ID: 1}
+		_, apiKey, err := service.GenerateApiKey(user, "test-1")
+		require.NoError(t, err)
+
+		_, apiKeyGot, err := service.GetDigestUserAndKey(apiKey.Digest)
+		require.NoError(t, err)
+		is.Equal(*apiKey, apiKeyGot)
+
+		err = service.DeleteAPIKey(apiKey.ID)
+		require.NoError(t, err)
+
+		_, _, err = service.GetDigestUserAndKey(apiKey.Digest)
+		require.Error(t, err)
+	})
+
+	t.Run("Successfully removes api-key from cache upon deletion", func(t *testing.T) {
+		user := portainer.User{ID: 1}
+		_, apiKey, err := service.GenerateApiKey(user, "test-1")
+		require.NoError(t, err)
+
+		_, apiKeyFromCache, ok := service.cache.Get(apiKey.Digest)
+		is.True(ok)
+		is.Equal(*apiKey, apiKeyFromCache)
+
+		err = service.DeleteAPIKey(apiKey.ID)
+		require.NoError(t, err)
+
+		_, _, ok = service.cache.Get(apiKey.Digest)
+		is.False(ok)
+	})
+}
+
+func Test_InvalidateUserKeyCache(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	_, store := datastore.MustNewTestStore(t, true, true)
+
+	service := NewAPIKeyService(store.APIKeyRepository(), store.User())
+
+	t.Run("Successfully updates evicts keys from cache", func(t *testing.T) {
+		// generate api keys
+		user := portainer.User{ID: 1}
+		_, apiKey1, err := service.GenerateApiKey(user, "test-1")
+		require.NoError(t, err)
+
+		_, apiKey2, err := service.GenerateApiKey(user, "test-2")
+		require.NoError(t, err)
+
+		// verify api keys are present in cache
+		_, apiKeyFromCache, ok := service.cache.Get(apiKey1.Digest)
+		is.True(ok)
+		is.Equal(*apiKey1, apiKeyFromCache)
+
+		_, apiKeyFromCache, ok = service.cache.Get(apiKey2.Digest)
+		is.True(ok)
+		is.Equal(*apiKey2, apiKeyFromCache)
+
+		// evict cache
+		ok = service.InvalidateUserKeyCache(user.ID)
+		is.True(ok)
+
+		// verify users keys have been flushed from cache
+		_, _, ok = service.cache.Get(apiKey1.Digest)
+		is.False(ok)
+
+		_, _, ok = service.cache.Get(apiKey2.Digest)
+		is.False(ok)
+	})
+
+	t.Run("User key eviction does not affect other users keys", func(t *testing.T) {
+		// generate keys for 2 users
+		user1 := portainer.User{ID: 1}
+		_, apiKey1, err := service.GenerateApiKey(user1, "test-1")
+		require.NoError(t, err)
+
+		user2 := portainer.User{ID: 2}
+		_, apiKey2, err := service.GenerateApiKey(user2, "test-2")
+		require.NoError(t, err)
+
+		// verify keys in cache
+		_, apiKeyFromCache, ok := service.cache.Get(apiKey1.Digest)
+		is.True(ok)
+		is.Equal(*apiKey1, apiKeyFromCache)
+
+		_, apiKeyFromCache, ok = service.cache.Get(apiKey2.Digest)
+		is.True(ok)
+		is.Equal(*apiKey2, apiKeyFromCache)
+
+		// evict key of single user from cache
+		ok = service.cache.InvalidateUserKeyCache(user1.ID)
+		is.True(ok)
+
+		// verify user1 key has been flushed from cache
+		_, _, ok = service.cache.Get(apiKey1.Digest)
+		is.False(ok)
+
+		// verify user2 key is still in cache
+		_, _, ok = service.cache.Get(apiKey2.Digest)
+		is.True(ok)
+	})
+}

api/archive/tar.go

@@ -0,0 +1,70 @@
+package archive
+
+import (
+	"archive/tar"
+	"bytes"
+)
+
+// TarFileInBuffer will create a tar archive containing a single file named via fileName and using the content
+// specified in fileContent. Returns the archive as a byte array.
+func TarFileInBuffer(fileContent []byte, fileName string, mode int64) ([]byte, error) {
+	var buffer bytes.Buffer
+	tarWriter := tar.NewWriter(&buffer)
+
+	header := &tar.Header{
+		Name: fileName,
+		Mode: mode,
+		Size: int64(len(fileContent)),
+	}
+
+	if err := tarWriter.WriteHeader(header); err != nil {
+		return nil, err
+	}
+
+	if _, err := tarWriter.Write(fileContent); err != nil {
+		return nil, err
+	}
+
+	if err := tarWriter.Close(); err != nil {
+		return nil, err
+	}
+
+	return buffer.Bytes(), nil
+}
+
+// tarFileInBuffer represents a tar archive buffer.
+type tarFileInBuffer struct {
+	b *bytes.Buffer
+	w *tar.Writer
+}
+
+func NewTarFileInBuffer() *tarFileInBuffer {
+	var b bytes.Buffer
+	return &tarFileInBuffer{b: &b, w: tar.NewWriter(&b)}
+}
+
+// Put puts a single file to tar archive buffer.
+func (t *tarFileInBuffer) Put(fileContent []byte, fileName string, mode int64) error {
+	hdr := &tar.Header{
+		Name: fileName,
+		Mode: mode,
+		Size: int64(len(fileContent)),
+	}
+
+	if err := t.w.WriteHeader(hdr); err != nil {
+		return err
+	}
+
+	_, err := t.w.Write(fileContent)
+
+	return err
+}
+
+// Bytes returns the archive as a byte array.
+func (t *tarFileInBuffer) Bytes() []byte {
+	return t.b.Bytes()
+}
+
+func (t *tarFileInBuffer) Close() error {
+	return t.w.Close()
+}

api/archive/targz.go

@@ -0,0 +1,132 @@
+package archive
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/portainer/portainer/api/filesystem"
+	"github.com/portainer/portainer/api/logs"
+)
+
+// TarGzDir creates a tar.gz archive and returns it's path.
+// abosolutePath should be an absolute path to a directory.
+// Archive name will be <directoryName>.tar.gz and will be placed next to the directory.
+func TarGzDir(absolutePath string) (string, error) {
+	targzPath := filepath.Join(absolutePath, filepath.Base(absolutePath)+".tar.gz")
+	outFile, err := os.Create(targzPath)
+	if err != nil {
+		return "", err
+	}
+	defer logs.CloseAndLogErr(outFile)
+
+	zipWriter := gzip.NewWriter(outFile)
+	defer logs.CloseAndLogErr(zipWriter)
+
+	tarWriter := tar.NewWriter(zipWriter)
+	defer logs.CloseAndLogErr(tarWriter)
+
+	err = filepath.Walk(absolutePath, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+
+		if path == targzPath {
+			return nil // skip archive file
+		}
+
+		pathInArchive := filepath.Clean(strings.TrimPrefix(path, absolutePath))
+		if pathInArchive == "" {
+			return nil // skip root dir
+		}
+
+		return addToArchive(tarWriter, pathInArchive, path, info)
+	})
+
+	return targzPath, err
+}
+
+func addToArchive(tarWriter *tar.Writer, pathInArchive string, path string, info os.FileInfo) error {
+	if info.IsDir() {
+		return nil
+	}
+
+	file, err := os.Open(path)
+	if err != nil {
+		return err
+	}
+
+	stat, err := file.Stat()
+	if err != nil {
+		return err
+	}
+
+	header, err := tar.FileInfoHeader(stat, stat.Name())
+	if err != nil {
+		return err
+	}
+	header.Name = pathInArchive // use relative paths in archive
+
+	err = tarWriter.WriteHeader(header)
+	if err != nil {
+		return err
+	}
+	if stat.IsDir() {
+		return nil
+	}
+
+	_, err = io.Copy(tarWriter, file)
+	return err
+}
+
+// ExtractTarGz reads a .tar.gz archive from the reader and extracts it into outputDirPath directory
+func ExtractTarGz(r io.Reader, outputDirPath string) error {
+	zipReader, err := gzip.NewReader(r)
+	if err != nil {
+		return err
+	}
+	defer logs.CloseAndLogErr(zipReader)
+
+	tarReader := tar.NewReader(zipReader)
+
+	for {
+		header, err := tarReader.Next()
+
+		if errors.Is(err, io.EOF) {
+			break
+		}
+
+		if err != nil {
+			return err
+		}
+
+		switch header.Typeflag {
+		case tar.TypeDir:
+			// skip, dir will be created with a file
+		case tar.TypeReg:
+			p := filesystem.JoinPaths(outputDirPath, header.Name)
+			if err := os.MkdirAll(filepath.Dir(p), 0o744); err != nil {
+				return fmt.Errorf("Failed to extract dir %s", filepath.Dir(p))
+			}
+			outFile, err := os.Create(p)
+			if err != nil {
+				return fmt.Errorf("Failed to create file %s", header.Name)
+			}
+			if _, err := io.Copy(outFile, tarReader); err != nil {
+				return fmt.Errorf("Failed to extract file %s", header.Name)
+			}
+			logs.CloseAndLogErr(outFile)
+		default:
+			return fmt.Errorf("tar: unknown type: %v in %s",
+				header.Typeflag,
+				header.Name)
+		}
+	}
+
+	return nil
+}

api/archive/targz_test.go

@@ -0,0 +1,168 @@
+package archive
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+
+	"github.com/portainer/portainer/api/filesystem"
+	"github.com/rs/zerolog/log"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func listFiles(dir string) []string {
+	items := make([]string, 0)
+
+	if err := filepath.Walk(dir, func(path string, info os.FileInfo, err error) error {
+		if path == dir {
+			return nil
+		}
+
+		items = append(items, path)
+
+		return nil
+	}); err != nil {
+		log.Warn().Err(err).Msg("failed to list files in directory")
+	}
+
+	return items
+}
+
+func Test_shouldCreateArchive(t *testing.T) {
+	t.Parallel()
+	tmpdir := t.TempDir()
+	content := []byte("content")
+
+	err := os.WriteFile(filesystem.JoinPaths(tmpdir, "outer"), content, 0600)
+	require.NoError(t, err)
+
+	err = os.MkdirAll(filesystem.JoinPaths(tmpdir, "dir"), 0700)
+	require.NoError(t, err)
+
+	err = os.WriteFile(filesystem.JoinPaths(tmpdir, "dir", ".dotfile"), content, 0600)
+	require.NoError(t, err)
+
+	err = os.WriteFile(filesystem.JoinPaths(tmpdir, "dir", "inner"), content, 0600)
+	require.NoError(t, err)
+
+	gzPath, err := TarGzDir(tmpdir)
+	require.NoError(t, err)
+	assert.Equal(t, filesystem.JoinPaths(tmpdir, filepath.Base(tmpdir)+".tar.gz"), gzPath)
+
+	extractionDir := t.TempDir()
+	cmd := exec.Command("tar", "-xzf", gzPath, "-C", extractionDir)
+	if err := cmd.Run(); err != nil {
+		t.Fatal("Failed to extract archive: ", err)
+	}
+	extractedFiles := listFiles(extractionDir)
+
+	wasExtracted := func(p string) {
+		fullpath := filesystem.JoinPaths(extractionDir, p)
+		assert.Contains(t, extractedFiles, fullpath)
+		copyContent, err := os.ReadFile(fullpath)
+		require.NoError(t, err)
+		assert.Equal(t, content, copyContent)
+	}
+
+	wasExtracted("outer")
+	wasExtracted("dir/inner")
+	wasExtracted("dir/.dotfile")
+}
+
+func Test_shouldCreateArchive2(t *testing.T) {
+	t.Parallel()
+	tmpdir := t.TempDir()
+	content := []byte("content")
+
+	err := os.WriteFile(filesystem.JoinPaths(tmpdir, "outer"), content, 0600)
+	require.NoError(t, err)
+
+	err = os.MkdirAll(filesystem.JoinPaths(tmpdir, "dir"), 0700)
+	require.NoError(t, err)
+
+	err = os.WriteFile(filesystem.JoinPaths(tmpdir, "dir", ".dotfile"), content, 0600)
+	require.NoError(t, err)
+
+	err = os.WriteFile(filesystem.JoinPaths(tmpdir, "dir", "inner"), content, 0600)
+	require.NoError(t, err)
+
+	gzPath, err := TarGzDir(tmpdir)
+	require.NoError(t, err)
+	assert.Equal(t, filesystem.JoinPaths(tmpdir, filepath.Base(tmpdir)+".tar.gz"), gzPath)
+
+	extractionDir := t.TempDir()
+	r, _ := os.Open(gzPath)
+	if err := ExtractTarGz(r, extractionDir); err != nil {
+		t.Fatal("Failed to extract archive: ", err)
+	}
+	extractedFiles := listFiles(extractionDir)
+
+	wasExtracted := func(p string) {
+		fullpath := filesystem.JoinPaths(extractionDir, p)
+		assert.Contains(t, extractedFiles, fullpath)
+		copyContent, _ := os.ReadFile(fullpath)
+		assert.Equal(t, content, copyContent)
+	}
+
+	wasExtracted("outer")
+	wasExtracted("dir/inner")
+	wasExtracted("dir/.dotfile")
+}
+
+func TestExtractTarGzPathTraversal(t *testing.T) {
+	t.Parallel()
+	testDir := t.TempDir()
+
+	// Create an evil file with a path traversal attempt
+	tarPath := filesystem.JoinPaths(testDir, "evil.tar.gz")
+
+	evilFile, err := os.Create(tarPath)
+	require.NoError(t, err)
+
+	gzWriter := gzip.NewWriter(evilFile)
+	tarWriter := tar.NewWriter(gzWriter)
+
+	content := []byte("evil content")
+
+	header := &tar.Header{
+		Name:     "../evil.txt",
+		Mode:     0600,
+		Size:     int64(len(content)),
+		Typeflag: tar.TypeReg,
+	}
+
+	err = tarWriter.WriteHeader(header)
+	require.NoError(t, err)
+
+	_, err = tarWriter.Write(content)
+	require.NoError(t, err)
+
+	err = tarWriter.Close()
+	require.NoError(t, err)
+
+	err = gzWriter.Close()
+	require.NoError(t, err)
+
+	err = evilFile.Close()
+	require.NoError(t, err)
+
+	// Attempt to extract the evil file
+	extractionDir := filesystem.JoinPaths(testDir, "extraction")
+	err = os.Mkdir(extractionDir, 0700)
+	require.NoError(t, err)
+
+	tarFile, err := os.Open(tarPath)
+	require.NoError(t, err)
+
+	// Check that the file didn't escape
+	err = ExtractTarGz(tarFile, extractionDir)
+	require.NoError(t, err)
+	require.NoFileExists(t, filesystem.JoinPaths(testDir, "evil.txt"))
+
+	err = tarFile.Close()
+	require.NoError(t, err)
+}

api/archive/zip.go

@@ -0,0 +1,73 @@
+package archive
+
+import (
+	"archive/zip"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/portainer/portainer/api/logs"
+
+	"github.com/pkg/errors"
+)
+
+// UnzipFile will decompress a zip archive, moving all files and folders
+// within the zip file (parameter 1) to an output directory (parameter 2).
+func UnzipFile(src string, dest string) error {
+	r, err := zip.OpenReader(src)
+	if err != nil {
+		return err
+	}
+	defer logs.CloseAndLogErr(r)
+
+	for _, f := range r.File {
+		p := filepath.Join(dest, f.Name)
+
+		// Check for ZipSlip. More Info: http://bit.ly/2MsjAWE
+		if !strings.HasPrefix(p, filepath.Clean(dest)+string(os.PathSeparator)) {
+			return fmt.Errorf("%s: illegal file path", p)
+		}
+
+		if f.FileInfo().IsDir() {
+			// Make Folder
+			if err := os.MkdirAll(p, os.ModePerm); err != nil {
+				return err
+			}
+
+			continue
+		}
+
+		if err := unzipFile(f, p); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func unzipFile(f *zip.File, p string) error {
+	// Make File
+	if err := os.MkdirAll(filepath.Dir(p), os.ModePerm); err != nil {
+		return errors.Wrapf(err, "unzipFile: can't make a path %s", p)
+	}
+
+	outFile, err := os.OpenFile(p, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, f.Mode())
+	if err != nil {
+		return errors.Wrapf(err, "unzipFile: can't create file %s", p)
+	}
+	defer logs.CloseAndLogErr(outFile)
+
+	rc, err := f.Open()
+	if err != nil {
+		return errors.Wrapf(err, "unzipFile: can't open zip file %s in the archive", f.Name)
+	}
+	defer logs.CloseAndLogErr(rc)
+
+	if _, err = io.Copy(outFile, rc); err != nil {
+		return errors.Wrapf(err, "unzipFile: can't copy an archived file content")
+	}
+
+	return nil
+}

api/archive/zip_test.go

@@ -0,0 +1,32 @@
+package archive
+
+import (
+	"testing"
+
+	"github.com/portainer/portainer/api/filesystem"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestUnzipFile(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	/*
+		Archive structure.
+		├── 0
+		│	├── 1
+		│	│	└── 2.txt
+		│	└── 1.txt
+		└── 0.txt
+	*/
+
+	err := UnzipFile("./testdata/sample_archive.zip", dir)
+
+	require.NoError(t, err)
+	archiveDir := dir + "/sample_archive"
+	assert.FileExists(t, filesystem.JoinPaths(archiveDir, "0.txt"))
+	assert.FileExists(t, filesystem.JoinPaths(archiveDir, "0", "1.txt"))
+	assert.FileExists(t, filesystem.JoinPaths(archiveDir, "0", "1", "2.txt"))
+
+}

api/aws/ecr/authorization_token.go

@@ -0,0 +1,61 @@
+package ecr
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"strings"
+	"time"
+)
+
+func (s *Service) GetEncodedAuthorizationToken(ctx context.Context) (token *string, expiry *time.Time, err error) {
+	getAuthorizationTokenOutput, err := s.client.GetAuthorizationToken(ctx, nil)
+	if err != nil {
+		return
+	}
+
+	if len(getAuthorizationTokenOutput.AuthorizationData) == 0 {
+		err = errors.New("AuthorizationData is empty")
+		return
+	}
+
+	authData := getAuthorizationTokenOutput.AuthorizationData[0]
+
+	token = authData.AuthorizationToken
+	expiry = authData.ExpiresAt
+
+	return
+}
+
+func (s *Service) GetAuthorizationToken(ctx context.Context) (token *string, expiry *time.Time, err error) {
+	tokenEncodedStr, expiry, err := s.GetEncodedAuthorizationToken(ctx)
+	if err != nil {
+		return
+	}
+
+	tokenByte, err := base64.StdEncoding.DecodeString(*tokenEncodedStr)
+	if err != nil {
+		return
+	}
+	tokenStr := string(tokenByte)
+	token = &tokenStr
+
+	return
+}
+
+func (s *Service) ParseAuthorizationToken(token string) (username string, password string, err error) {
+	if len(token) == 0 {
+		return
+	}
+
+	splitToken := strings.Split(token, ":")
+	if len(splitToken) < 2 {
+		err = errors.New("invalid ECR authorization token")
+		return
+	}
+
+	username = splitToken[0]
+	password = splitToken[1]
+
+	return
+}

api/aws/ecr/ecr.go

@@ -0,0 +1,41 @@
+package ecr
+
+import (
+	"github.com/aws/aws-sdk-go-v2/aws"
+	"github.com/aws/aws-sdk-go-v2/credentials"
+	"github.com/aws/aws-sdk-go-v2/service/ecr"
+)
+
+// Registry represents an ECR registry endpoint information.
+// This struct is used to parse and validate ECR endpoint URLs.
+type Registry struct {
+	ID     string // AWS account ID (empty for accountless endpoints like "ecr-fips.us-west-1.amazonaws.com")
+	FIPS   bool   // Whether this is a FIPS endpoint (contains "-fips" in the URL)
+	Region string // AWS region (e.g., "us-east-1", "us-gov-west-1")
+	Public bool   // Whether this is ecr-public.aws.com
+}
+
+type (
+	Service struct {
+		accessKey string
+		secretKey string
+		region    string
+		client    *ecr.Client
+	}
+)
+
+func NewService(accessKey, secretKey, region string) *Service {
+	options := ecr.Options{
+		Region:      region,
+		Credentials: aws.NewCredentialsCache(credentials.NewStaticCredentialsProvider(accessKey, secretKey, "")),
+	}
+
+	client := ecr.New(options)
+
+	return &Service{
+		accessKey: accessKey,
+		secretKey: secretKey,
+		region:    region,
+		client:    client,
+	}
+}

api/aws/ecr/parse_endpoints.go

@@ -0,0 +1,70 @@
+package ecr
+
+import (
+	"fmt"
+	"net/url"
+	"regexp"
+	"strings"
+)
+
+// ecrEndpointPattern matches all valid ECR endpoints including account-prefixed and accountless formats.
+// Based on AWS ECR credential helper regex but extended to support accountless endpoints.
+//
+// Supported formats:
+//   - Account-prefixed: 123456789012.dkr.ecr-fips.us-east-1.amazonaws.com
+//   - Account-prefixed (hyphen): 123456789012.dkr-ecr-fips.us-west-1.on.aws
+//   - Accountless service: ecr-fips.us-west-1.amazonaws.com
+//   - Accountless API: ecr-fips.us-east-1.api.aws
+//   - Non-FIPS variants: All formats above without "-fips"
+//
+// Regex groups:
+//   - Group 1: Full account prefix (optional) - e.g., "123456789012.dkr." or "123456789012.dkr-"
+//   - Group 2: Account ID (optional) - e.g., "123456789012"
+//   - Group 3: FIPS flag (optional) - either "-fips" or empty string
+//   - Group 4: Region - e.g., "us-east-1", "us-gov-west-1"
+//   - Group 5: Domain suffix - e.g., "amazonaws.com", "api.aws"
+var ecrEndpointPattern = regexp.MustCompile(
+	`^((\d{12})\.dkr[\.\-])?ecr(\-fips)?\.([a-zA-Z0-9][a-zA-Z0-9-_]*)\.(amazonaws\.(?:com(?:\.cn)?|eu)|api\.aws|on\.(?:aws|amazonwebservices\.com\.cn)|sc2s\.sgov\.gov|c2s\.ic\.gov|cloud\.adc-e\.uk|csp\.hci\.ic\.gov)$`,
+)
+
+// ParseECREndpoint parses an ECR registry URL and extracts registry information.
+
+// This function replaces the AWS ECR credential helper library's ExtractRegistry function,
+// which only supports account-prefixed endpoints.
+//
+// Reference: https://docs.aws.amazon.com/general/latest/gr/ecr.html
+func ParseECREndpoint(urlStr string) (*Registry, error) {
+	// Normalize URL by adding https:// prefix if not present
+	if !strings.HasPrefix(urlStr, "https://") && !strings.HasPrefix(urlStr, "http://") {
+		urlStr = "https://" + urlStr
+	}
+
+	u, err := url.Parse(urlStr)
+	if err != nil {
+		return nil, fmt.Errorf("invalid URL: %w", err)
+	}
+
+	hostname := u.Hostname()
+
+	// Special case: ECR Public
+	// ECR Public uses a different domain and doesn't have FIPS variant
+	if hostname == "ecr-public.aws.com" {
+		return &Registry{
+			FIPS:   false,
+			Public: true,
+		}, nil
+	}
+
+	// Parse standard ECR endpoints using regex
+	matches := ecrEndpointPattern.FindStringSubmatch(hostname)
+	if len(matches) == 0 {
+		return nil, fmt.Errorf("not a valid ECR endpoint: %s", hostname)
+	}
+
+	return &Registry{
+		ID:     matches[2],            // Account ID (may be empty for accountless endpoints)
+		FIPS:   matches[3] == "-fips", // Check if "-fips" is present
+		Region: matches[4],            // AWS region
+		Public: false,
+	}, nil
+}

api/aws/ecr/parse_endpoints_test.go

@@ -0,0 +1,254 @@
+package ecr
+
+import (
+	"testing"
+)
+
+func TestParseECREndpoint(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		name      string
+		url       string
+		want      *Registry
+		wantError bool
+	}{
+		// Standard AWS Commercial - Account-prefixed FIPS
+		{
+			name: "account-prefixed FIPS us-east-1",
+			url:  "123456789012.dkr.ecr-fips.us-east-1.amazonaws.com",
+			want: &Registry{
+				ID:     "123456789012",
+				FIPS:   true,
+				Region: "us-east-1",
+				Public: false,
+			},
+		},
+		{
+			name: "account-prefixed FIPS us-west-2",
+			url:  "123456789012.dkr.ecr-fips.us-west-2.amazonaws.com",
+			want: &Registry{
+				ID:     "123456789012",
+				FIPS:   true,
+				Region: "us-west-2",
+				Public: false,
+			},
+		},
+
+		// Accountless FIPS service endpoints
+		{
+			name: "accountless FIPS us-west-1",
+			url:  "ecr-fips.us-west-1.amazonaws.com",
+			want: &Registry{
+				ID:     "",
+				FIPS:   true,
+				Region: "us-west-1",
+				Public: false,
+			},
+		},
+		{
+			name: "accountless FIPS us-east-2",
+			url:  "ecr-fips.us-east-2.amazonaws.com",
+			want: &Registry{
+				ID:     "",
+				FIPS:   true,
+				Region: "us-east-2",
+				Public: false,
+			},
+		},
+
+		// Accountless FIPS API endpoints
+		{
+			name: "accountless FIPS API us-west-1",
+			url:  "ecr-fips.us-west-1.api.aws",
+			want: &Registry{
+				ID:     "",
+				FIPS:   true,
+				Region: "us-west-1",
+				Public: false,
+			},
+		},
+		{
+			name: "accountless FIPS API us-east-1",
+			url:  "ecr-fips.us-east-1.api.aws",
+			want: &Registry{
+				ID:     "",
+				FIPS:   true,
+				Region: "us-east-1",
+				Public: false,
+			},
+		},
+
+		// on.aws domain with hyphen separator
+		{
+			name: "account-prefixed FIPS hyphen us-west-1",
+			url:  "123456789012.dkr-ecr-fips.us-west-1.on.aws",
+			want: &Registry{
+				ID:     "123456789012",
+				FIPS:   true,
+				Region: "us-west-1",
+				Public: false,
+			},
+		},
+		{
+			name: "account-prefixed FIPS hyphen us-east-2",
+			url:  "123456789012.dkr-ecr-fips.us-east-2.on.aws",
+			want: &Registry{
+				ID:     "123456789012",
+				FIPS:   true,
+				Region: "us-east-2",
+				Public: false,
+			},
+		},
+
+		// AWS GovCloud
+		{
+			name: "account-prefixed FIPS us-gov-east-1",
+			url:  "123456789012.dkr.ecr-fips.us-gov-east-1.amazonaws.com",
+			want: &Registry{
+				ID:     "123456789012",
+				FIPS:   true,
+				Region: "us-gov-east-1",
+				Public: false,
+			},
+		},
+		{
+			name: "account-prefixed FIPS us-gov-west-1",
+			url:  "123456789012.dkr.ecr-fips.us-gov-west-1.amazonaws.com",
+			want: &Registry{
+				ID:     "123456789012",
+				FIPS:   true,
+				Region: "us-gov-west-1",
+				Public: false,
+			},
+		},
+		{
+			name: "accountless FIPS us-gov-west-1",
+			url:  "ecr-fips.us-gov-west-1.amazonaws.com",
+			want: &Registry{
+				ID:     "",
+				FIPS:   true,
+				Region: "us-gov-west-1",
+				Public: false,
+			},
+		},
+		{
+			name: "accountless FIPS API us-gov-east-1",
+			url:  "ecr-fips.us-gov-east-1.api.aws",
+			want: &Registry{
+				ID:     "",
+				FIPS:   true,
+				Region: "us-gov-east-1",
+				Public: false,
+			},
+		},
+
+		// ECR Public
+		{
+			name: "ecr-public",
+			url:  "ecr-public.aws.com",
+			want: &Registry{
+				ID:     "",
+				FIPS:   false,
+				Region: "",
+				Public: true,
+			},
+		},
+
+		// Non-FIPS endpoints (valid ECR but FIPS=false)
+		{
+			name: "account-prefixed non-FIPS us-east-1",
+			url:  "123456789012.dkr.ecr.us-east-1.amazonaws.com",
+			want: &Registry{
+				ID:     "123456789012",
+				FIPS:   false,
+				Region: "us-east-1",
+				Public: false,
+			},
+		},
+		{
+			name: "accountless non-FIPS us-west-1",
+			url:  "ecr.us-west-1.amazonaws.com",
+			want: &Registry{
+				ID:     "",
+				FIPS:   false,
+				Region: "us-west-1",
+				Public: false,
+			},
+		},
+		{
+			name: "accountless non-FIPS API us-east-2",
+			url:  "ecr.us-east-2.api.aws",
+			want: &Registry{
+				ID:     "",
+				FIPS:   false,
+				Region: "us-east-2",
+				Public: false,
+			},
+		},
+
+		// URLs with https:// prefix
+		{
+			name: "with https prefix",
+			url:  "https://ecr-fips.us-west-1.amazonaws.com",
+			want: &Registry{
+				ID:     "",
+				FIPS:   true,
+				Region: "us-west-1",
+				Public: false,
+			},
+		},
+
+		// Invalid endpoints
+		{
+			name:      "not an ECR URL",
+			url:       "not-an-ecr-url.com",
+			wantError: true,
+		},
+		{
+			name:      "invalid account ID length",
+			url:       "123.dkr.ecr-fips.us-east-1.amazonaws.com",
+			wantError: true,
+		},
+		{
+			name:      "empty string",
+			url:       "",
+			wantError: true,
+		},
+		{
+			name:      "docker hub",
+			url:       "docker.io",
+			wantError: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := ParseECREndpoint(tt.url)
+
+			if tt.wantError {
+				if err == nil {
+					t.Errorf("ParseECREndpoint() expected error but got none")
+				}
+				return
+			}
+
+			if err != nil {
+				t.Errorf("ParseECREndpoint() unexpected error: %v", err)
+				return
+			}
+
+			if got.ID != tt.want.ID {
+				t.Errorf("ParseECREndpoint() ID = %v, want %v", got.ID, tt.want.ID)
+			}
+			if got.FIPS != tt.want.FIPS {
+				t.Errorf("ParseECREndpoint() FIPS = %v, want %v", got.FIPS, tt.want.FIPS)
+			}
+			if got.Region != tt.want.Region {
+				t.Errorf("ParseECREndpoint() Region = %v, want %v", got.Region, tt.want.Region)
+			}
+			if got.Public != tt.want.Public {
+				t.Errorf("ParseECREndpoint() Public = %v, want %v", got.Public, tt.want.Public)
+			}
+		})
+	}
+}

api/backup/backup.go

@@ -0,0 +1,110 @@
+package backup
+
+import (
+	"fmt"
+	"os"
+	"path"
+	"path/filepath"
+	"time"
+
+	"github.com/portainer/portainer/api/archive"
+	"github.com/portainer/portainer/api/crypto"
+	"github.com/portainer/portainer/api/dataservices"
+	"github.com/portainer/portainer/api/filesystem"
+	"github.com/portainer/portainer/api/http/offlinegate"
+	"github.com/portainer/portainer/api/logs"
+
+	"github.com/pkg/errors"
+	"github.com/rs/zerolog/log"
+)
+
+const rwxr__r__ os.FileMode = 0o744
+
+var filesToBackup = []string{
+	"certs",
+	"chisel",
+	"compose",
+	"config.json",
+	"custom_templates",
+	"edge_jobs",
+	"edge_stacks",
+	"extensions",
+	"portainer.key",
+	"portainer.pub",
+	"tls",
+}
+
+// Creates a tar.gz system archive and encrypts it if password is not empty. Returns a path to the archive file.
+func CreateBackupArchive(password string, gate *offlinegate.OfflineGate, datastore dataservices.DataStore, filestorePath string) (string, error) {
+	backupDirPath, err := backupDatabaseAndFilesystem(gate, datastore, filestorePath)
+	if err != nil {
+		return "", err
+	}
+
+	archivePath, err := archive.TarGzDir(backupDirPath)
+	if err != nil {
+		return "", errors.Wrap(err, "Failed to make an archive")
+	}
+
+	if password != "" {
+		archivePath, err = encrypt(archivePath, password)
+		if err != nil {
+			return "", errors.Wrap(err, "Failed to encrypt backup with the password")
+		}
+	}
+
+	return archivePath, nil
+}
+
+func backupDatabaseAndFilesystem(gate *offlinegate.OfflineGate, datastore dataservices.DataStore, filestorePath string) (string, error) {
+	unlock := gate.Lock()
+	defer unlock()
+
+	backupDirPath := filepath.Join(filestorePath, "backup", time.Now().Format("2006-01-02_15-04-05"))
+	if err := os.MkdirAll(backupDirPath, rwxr__r__); err != nil {
+		return "", errors.Wrap(err, "Failed to create backup dir")
+	}
+
+	// new export
+	exportFilename := path.Join(backupDirPath, fmt.Sprintf("export-%d.json", time.Now().Unix()))
+
+	if err := datastore.Export(exportFilename); err != nil {
+		log.Error().Err(err).Str("filename", exportFilename).Msg("failed to export")
+	} else {
+		log.Debug().Str("filename", exportFilename).Msg("file exported")
+	}
+
+	if err := backupDb(backupDirPath, datastore); err != nil {
+		return "", errors.Wrap(err, "Failed to backup database")
+	}
+
+	for _, filename := range filesToBackup {
+		if err := filesystem.CopyPath(filepath.Join(filestorePath, filename), backupDirPath); err != nil {
+			return "", errors.Wrap(err, "Failed to create backup file")
+		}
+	}
+
+	return backupDirPath, nil
+}
+
+func backupDb(backupDirPath string, datastore dataservices.DataStore) error {
+	dbFileName := datastore.Connection().GetDatabaseFileName()
+	_, err := datastore.Backup(filepath.Join(backupDirPath, dbFileName))
+	return err
+}
+
+func encrypt(path string, passphrase string) (string, error) {
+	in, err := os.Open(path)
+	if err != nil {
+		return "", err
+	}
+	defer logs.CloseAndLogErr(in)
+
+	outFileName := path + ".encrypted"
+	out, err := os.Create(outFileName)
+	if err != nil {
+		return "", err
+	}
+
+	return outFileName, crypto.AesEncrypt(in, out, []byte(passphrase))
+}

api/backup/backup_test.go

@@ -0,0 +1,274 @@
+package backup
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/portainer/portainer/api/archive"
+	"github.com/portainer/portainer/api/crypto"
+	"github.com/portainer/portainer/api/datastore"
+	"github.com/portainer/portainer/api/filesystem"
+	"github.com/portainer/portainer/api/http/offlinegate"
+	"github.com/portainer/portainer/pkg/fips"
+
+	"github.com/stretchr/testify/require"
+)
+
+func init() {
+	fips.InitFIPS(false)
+}
+
+func TestGetRestoreSourcePath_DBAtRoot(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	err := os.WriteFile(filesystem.JoinPaths(dir, "portainer.db"), []byte("db"), 0o600)
+	require.NoError(t, err)
+
+	result, err := getRestoreSourcePath(dir)
+	require.NoError(t, err)
+	require.Equal(t, dir, result)
+}
+
+func TestGetRestoreSourcePath_EncryptedDBAtRoot(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	err := os.WriteFile(filesystem.JoinPaths(dir, "portainer.edb"), []byte("db"), 0o600)
+	require.NoError(t, err)
+
+	result, err := getRestoreSourcePath(dir)
+	require.NoError(t, err)
+	require.Equal(t, dir, result)
+}
+
+func TestGetRestoreSourcePath_DBInSubdirectory(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	sub := filesystem.JoinPaths(dir, "backup-2024-01-01")
+	err := os.Mkdir(sub, 0o700)
+	require.NoError(t, err)
+
+	err = os.WriteFile(filesystem.JoinPaths(sub, "portainer.db"), []byte("db"), 0o600)
+	require.NoError(t, err)
+
+	result, err := getRestoreSourcePath(dir)
+	require.NoError(t, err)
+	require.Equal(t, sub, result)
+}
+
+func TestGetRestoreSourcePath_NoDBFile(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	err := os.WriteFile(filesystem.JoinPaths(dir, "other.file"), []byte("data"), 0o600)
+	require.NoError(t, err)
+
+	result, err := getRestoreSourcePath(dir)
+	require.NoError(t, err)
+	require.Equal(t, dir, result)
+}
+
+func TestGetRestoreSourcePath_EmptyDir(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+
+	result, err := getRestoreSourcePath(dir)
+	require.NoError(t, err)
+	require.Equal(t, dir, result)
+}
+
+func TestEncryptDecrypt_RoundTrip(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	plaintext := []byte("sensitive portainer backup data")
+
+	srcPath := filesystem.JoinPaths(dir, "archive.tar.gz")
+	err := os.WriteFile(srcPath, plaintext, 0o600)
+	require.NoError(t, err)
+
+	encryptedPath, err := encrypt(srcPath, "mysecretpassword")
+	require.NoError(t, err)
+	require.Equal(t, srcPath+".encrypted", encryptedPath)
+
+	encryptedData, err := os.ReadFile(encryptedPath)
+	require.NoError(t, err)
+
+	decryptedReader, err := crypto.AesDecrypt(bytes.NewReader(encryptedData), []byte("mysecretpassword"))
+	require.NoError(t, err)
+
+	decrypted, err := io.ReadAll(decryptedReader)
+	require.NoError(t, err)
+	require.Equal(t, plaintext, decrypted)
+}
+
+func TestEncryptDecrypt_WrongPassword(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+
+	srcPath := filesystem.JoinPaths(dir, "archive.tar.gz")
+	err := os.WriteFile(srcPath, []byte("data"), 0o600)
+	require.NoError(t, err)
+
+	encryptedPath, err := encrypt(srcPath, "correctpassword")
+	require.NoError(t, err)
+
+	encryptedData, err := os.ReadFile(encryptedPath)
+	require.NoError(t, err)
+
+	_, err = crypto.AesDecrypt(bytes.NewReader(encryptedData), []byte("wrongpassword"))
+	require.Error(t, err)
+}
+
+func TestCreateBackupArchive_NoPassword(t *testing.T) {
+	t.Parallel()
+
+	_, store := datastore.MustNewTestStore(t, true, false)
+	storePath := store.GetConnection().GetStorePath()
+	gate := offlinegate.NewOfflineGate()
+
+	archivePath, err := CreateBackupArchive("", gate, store, storePath)
+	require.NoError(t, err)
+
+	f, err := os.Open(archivePath)
+	require.NoError(t, err)
+	t.Cleanup(func() {
+		err := f.Close()
+		require.NoError(t, err)
+	})
+
+	extractDir := t.TempDir()
+	err = archive.ExtractTarGz(f, extractDir)
+	require.NoError(t, err)
+
+	dbFound := false
+	err = filepath.Walk(extractDir, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if info.Name() == "portainer.db" {
+			dbFound = true
+		}
+
+		return nil
+	})
+	require.NoError(t, err)
+	require.True(t, dbFound, "archive should contain portainer.db")
+}
+
+func TestCreateBackupArchive_WithPassword(t *testing.T) {
+	t.Parallel()
+
+	_, store := datastore.MustNewTestStore(t, true, false)
+	storePath := store.GetConnection().GetStorePath()
+	gate := offlinegate.NewOfflineGate()
+
+	archivePath, err := CreateBackupArchive("backup-secret", gate, store, storePath)
+	require.NoError(t, err)
+	require.Contains(t, archivePath, ".encrypted")
+
+	encryptedData, err := os.ReadFile(archivePath)
+	require.NoError(t, err)
+
+	decryptedReader, err := crypto.AesDecrypt(bytes.NewReader(encryptedData), []byte("backup-secret"))
+	require.NoError(t, err)
+
+	extractDir := t.TempDir()
+	err = archive.ExtractTarGz(decryptedReader, extractDir)
+	require.NoError(t, err)
+
+	dbFound := false
+	err = filepath.Walk(extractDir, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if info.Name() == "portainer.db" {
+			dbFound = true
+		}
+
+		return nil
+	})
+	require.NoError(t, err)
+	require.True(t, dbFound, "decrypted archive should contain portainer.db")
+}
+
+func TestRestoreArchive_NoPassword(t *testing.T) {
+	t.Parallel()
+
+	_, store1 := datastore.MustNewTestStore(t, true, false)
+	storePath1 := store1.GetConnection().GetStorePath()
+	gate := offlinegate.NewOfflineGate()
+
+	archivePath, err := CreateBackupArchive("", gate, store1, storePath1)
+	require.NoError(t, err)
+
+	archiveData, err := os.ReadFile(archivePath)
+	require.NoError(t, err)
+
+	_, store2 := datastore.MustNewTestStore(t, true, false)
+	storePath2 := store2.GetConnection().GetStorePath()
+
+	ctx, cancel := context.WithCancel(t.Context())
+	err = RestoreArchive(bytes.NewReader(archiveData), "", storePath2, gate, store2, cancel)
+	require.NoError(t, err)
+
+	require.ErrorIs(t, ctx.Err(), context.Canceled)
+
+	_, err = os.Stat(filesystem.JoinPaths(storePath2, "portainer.db"))
+	require.NoError(t, err)
+}
+
+func TestRestoreArchive_WithPassword(t *testing.T) {
+	t.Parallel()
+
+	_, store1 := datastore.MustNewTestStore(t, true, false)
+	storePath1 := store1.GetConnection().GetStorePath()
+	gate := offlinegate.NewOfflineGate()
+
+	archivePath, err := CreateBackupArchive("restore-secret", gate, store1, storePath1)
+	require.NoError(t, err)
+
+	archiveData, err := os.ReadFile(archivePath)
+	require.NoError(t, err)
+
+	_, store2 := datastore.MustNewTestStore(t, true, false)
+	storePath2 := store2.GetConnection().GetStorePath()
+
+	ctx, cancel := context.WithCancel(t.Context())
+	err = RestoreArchive(bytes.NewReader(archiveData), "restore-secret", storePath2, gate, store2, cancel)
+	require.NoError(t, err)
+
+	require.ErrorIs(t, ctx.Err(), context.Canceled)
+
+	_, err = os.Stat(filesystem.JoinPaths(storePath2, "portainer.db"))
+	require.NoError(t, err)
+}
+
+func TestRestoreArchive_WrongPassword(t *testing.T) {
+	t.Parallel()
+
+	_, store1 := datastore.MustNewTestStore(t, true, false)
+	storePath1 := store1.GetConnection().GetStorePath()
+	gate := offlinegate.NewOfflineGate()
+
+	archivePath, err := CreateBackupArchive("correct-password", gate, store1, storePath1)
+	require.NoError(t, err)
+
+	archiveData, err := os.ReadFile(archivePath)
+	require.NoError(t, err)
+
+	_, store2 := datastore.MustNewTestStore(t, true, false)
+	storePath2 := store2.GetConnection().GetStorePath()
+
+	_, cancel := context.WithCancel(t.Context())
+	err = RestoreArchive(bytes.NewReader(archiveData), "wrong-password", storePath2, gate, store2, cancel)
+	require.Error(t, err)
+}

api/backup/restore.go

@@ -0,0 +1,121 @@
+package backup
+
+import (
+	"context"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"time"
+
+	"github.com/pkg/errors"
+	"github.com/portainer/portainer/api/archive"
+	"github.com/portainer/portainer/api/crypto"
+	"github.com/portainer/portainer/api/database/boltdb"
+	"github.com/portainer/portainer/api/dataservices"
+	"github.com/portainer/portainer/api/filesystem"
+	"github.com/portainer/portainer/api/http/offlinegate"
+
+	"github.com/rs/zerolog/log"
+)
+
+var filesToRestore = append(filesToBackup, "portainer.db")
+
+// Restores system state from backup archive, will trigger system shutdown, when finished.
+func RestoreArchive(archive io.Reader, password string, filestorePath string, gate *offlinegate.OfflineGate, datastore dataservices.DataStore, shutdownTrigger context.CancelFunc) error {
+	var err error
+	if password != "" {
+		archive, err = decrypt(archive, password)
+		if err != nil {
+			return errors.Wrap(err, "failed to decrypt the archive. Please ensure the password is correct and try again")
+		}
+	}
+
+	restorePath := filepath.Join(filestorePath, "restore", time.Now().Format("20060102150405"))
+	defer func() {
+		if err := os.RemoveAll(filepath.Dir(restorePath)); err != nil {
+			log.Warn().Err(err).Msg("failed to clean up restore files")
+		}
+	}()
+
+	if err := extractArchive(archive, restorePath); err != nil {
+		return errors.Wrap(err, "cannot extract files from the archive. Please ensure the password is correct and try again")
+	}
+
+	unlock := gate.Lock()
+	defer unlock()
+
+	if err := datastore.Close(); err != nil {
+		return errors.Wrap(err, "Failed to stop db")
+	}
+
+	// At some point, backups were created containing a subdirectory, now we need to handle both
+	restorePath, err = getRestoreSourcePath(restorePath)
+	if err != nil {
+		return errors.Wrap(err, "failed to restore from backup. Portainer database missing from backup file")
+	}
+
+	if err := restoreFiles(restorePath, filestorePath); err != nil {
+		return errors.Wrap(err, "failed to restore the system state")
+	}
+
+	shutdownTrigger()
+	return nil
+}
+
+func decrypt(r io.Reader, password string) (io.Reader, error) {
+	return crypto.AesDecrypt(r, []byte(password))
+}
+
+func extractArchive(r io.Reader, destinationDirPath string) error {
+	return archive.ExtractTarGz(r, destinationDirPath)
+}
+
+func getRestoreSourcePath(dir string) (string, error) {
+	// find portainer.db or portainer.edb file. Return the parent directory
+	var portainerdbRegex = regexp.MustCompile(`^portainer.e?db$`)
+
+	backupDirPath := dir
+	err := filepath.WalkDir(dir, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+
+		if portainerdbRegex.MatchString(d.Name()) {
+			backupDirPath = filepath.Dir(path)
+			return filepath.SkipDir
+		}
+		return nil
+	})
+
+	return backupDirPath, err
+}
+
+func restoreFiles(srcDir string, destinationDir string) error {
+	for _, filename := range filesToRestore {
+		if err := filesystem.CopyPath(filepath.Join(srcDir, filename), destinationDir); err != nil {
+			return err
+		}
+	}
+
+	// TODO:  This is very boltdb module specific once again due to the filename.  Move to bolt module? Refactor for another day
+
+	// Prevent the possibility of having both databases.  Remove any default new instance
+	if err := os.Remove(filepath.Join(destinationDir, boltdb.DatabaseFileName)); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+
+	if err := os.Remove(filepath.Join(destinationDir, boltdb.EncryptedDatabaseFileName)); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+
+	// Now copy the database.  It'll be either portainer.db or portainer.edb
+
+	// Note: CopyPath does not return an error if the source file doesn't exist
+	if err := filesystem.CopyPath(filepath.Join(srcDir, boltdb.EncryptedDatabaseFileName), destinationDir); err != nil {
+		return err
+	}
+
+	return filesystem.CopyPath(filepath.Join(srcDir, boltdb.DatabaseFileName), destinationDir)
+}

api/chisel/crypto/crypto.go

@@ -0,0 +1,61 @@
+package crypto
+
+import (
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/x509"
+	"encoding/pem"
+	"fmt"
+	"io"
+	"math/big"
+
+	chshare "github.com/jpillora/chisel/share"
+)
+
+var one = new(big.Int).SetInt64(1)
+
+// GenerateGo119CompatibleKey This function is basically copied from chshare.GenerateKey.
+func GenerateGo119CompatibleKey(seed string) ([]byte, error) {
+	r := chshare.NewDetermRand([]byte(seed))
+	priv, err := ecdsaGenerateKey(elliptic.P256(), r)
+	if err != nil {
+		return nil, err
+	}
+	b, err := x509.MarshalECPrivateKey(priv)
+	if err != nil {
+		return nil, fmt.Errorf("Unable to marshal ECDSA private key: %w", err)
+	}
+	return pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: b}), nil
+}
+
+// This function is copied from Go1.19
+func randFieldElement(c elliptic.Curve, rand io.Reader) (k *big.Int, err error) {
+	params := c.Params()
+	// Note that for P-521 this will actually be 63 bits more than the order, as
+	// division rounds down, but the extra bit is inconsequential.
+	b := make([]byte, params.N.BitLen()/8+8)
+	_, err = io.ReadFull(rand, b)
+	if err != nil {
+		return
+	}
+
+	k = new(big.Int).SetBytes(b)
+	n := new(big.Int).Sub(params.N, one)
+	k.Mod(k, n)
+	k.Add(k, one)
+	return
+}
+
+// This function is copied from Go1.19
+func ecdsaGenerateKey(c elliptic.Curve, rand io.Reader) (*ecdsa.PrivateKey, error) {
+	k, err := randFieldElement(c, rand)
+	if err != nil {
+		return nil, err
+	}
+
+	priv := new(ecdsa.PrivateKey)
+	priv.Curve = c
+	priv.D = k
+	priv.X, priv.Y = c.ScalarBaseMult(k.Bytes())
+	return priv, nil
+}

api/chisel/crypto/crypto_test.go

@@ -0,0 +1,38 @@
+package crypto
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestGenerateGo119CompatibleKey(t *testing.T) {
+	t.Parallel()
+	type args struct {
+		seed string
+	}
+	tests := []struct {
+		name    string
+		args    args
+		want    []byte
+		wantErr bool
+	}{
+		{
+			name:    "Generate Go 1.19 compatible private key with a given seed",
+			args:    args{seed: "94qh17MCIk8BOkiI"},
+			want:    []byte("-----BEGIN EC PRIVATE KEY-----\nMHcCAQEEIHeohwk0Gy3RHVVViaHz7pz/HOiqA7fkv1FTM3mGgfT3oAoGCCqGSM49\nAwEHoUQDQgAEN7riX06xDsLNPuUmOvYFluNEakcFwZZRVvOcIYk/9VYnanDzW0Km\n8/BUUiKyJDuuGdS4fj9SlQ4iL8yBK01uKg==\n-----END EC PRIVATE KEY-----\n"),
+			wantErr: false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := GenerateGo119CompatibleKey(tt.args.seed)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("GenerateGo119CompatibleKey() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("GenerateGo119CompatibleKey()\ngot: Z %v\nwant: %v", got, tt.want)
+			}
+		})
+	}
+}

api/chisel/key.go

@@ -0,0 +1,24 @@
+package chisel
+
+import (
+	"encoding/base64"
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+// GenerateEdgeKey will generate a key that can be used by an Edge agent to register with a Portainer instance.
+// The key represents the following data in this particular format:
+// portainer_instance_url|tunnel_server_addr|tunnel_server_fingerprint|endpoint_ID
+// The key returned by this function is a base64 encoded version of the data.
+func (service *Service) GenerateEdgeKey(url, host string, endpointIdentifier int) string {
+	keyInformation := []string{
+		url,
+		fmt.Sprintf("%s:%s", host, service.serverPort),
+		service.serverFingerprint,
+		strconv.Itoa(endpointIdentifier),
+	}
+
+	key := strings.Join(keyInformation, "|")
+	return base64.RawStdEncoding.EncodeToString([]byte(key))
+}

api/chisel/service.go

@@ -0,0 +1,339 @@
+package chisel
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"sync"
+	"time"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+	"github.com/portainer/portainer/api/http/proxy"
+	"github.com/portainer/portainer/pkg/schedule"
+
+	chserver "github.com/jpillora/chisel/server"
+	"github.com/jpillora/chisel/share/ccrypto"
+	"github.com/rs/zerolog/log"
+)
+
+const (
+	tunnelCleanupInterval   = 10 * time.Second
+	activeTimeout           = 4*time.Minute + 30*time.Second
+	pingTimeout             = 8 * time.Second
+	tunnelKeepAliveInterval = 25 * time.Second
+)
+
+// Service represents a service to manage the state of multiple reverse tunnels.
+// It is used to start a reverse tunnel server and to manage the connection status of each tunnel
+// connected to the tunnel server.
+type Service struct {
+	serverFingerprint      string
+	serverPort             string
+	activeTunnels          map[portainer.EndpointID]*portainer.TunnelDetails
+	edgeJobs               map[portainer.EndpointID][]portainer.EdgeJob
+	dataStore              dataservices.DataStore
+	snapshotService        portainer.SnapshotService
+	chiselServer           *chserver.Server
+	shutdownCtx            context.Context
+	ProxyManager           *proxy.Manager
+	mu                     sync.RWMutex
+	fileService            portainer.FileService
+	defaultCheckinInterval int
+}
+
+// NewService returns a pointer to a new instance of Service
+func NewService(dataStore dataservices.DataStore, shutdownCtx context.Context, fileService portainer.FileService) *Service {
+	defaultCheckinInterval := portainer.DefaultEdgeAgentCheckinIntervalInSeconds
+
+	settings, err := dataStore.Settings().Settings()
+	if err == nil {
+		defaultCheckinInterval = settings.EdgeAgentCheckinInterval
+	} else {
+		log.Error().Err(err).Msg("unable to retrieve the settings from the database")
+	}
+
+	return &Service{
+		activeTunnels:          make(map[portainer.EndpointID]*portainer.TunnelDetails),
+		edgeJobs:               make(map[portainer.EndpointID][]portainer.EdgeJob),
+		dataStore:              dataStore,
+		shutdownCtx:            shutdownCtx,
+		fileService:            fileService,
+		defaultCheckinInterval: defaultCheckinInterval,
+	}
+}
+
+// pingAgent ping the given agent so that the agent can keep the tunnel alive
+func (service *Service) pingAgent(endpointID portainer.EndpointID) error {
+	endpoint, err := service.dataStore.Endpoint().Endpoint(endpointID)
+	if err != nil {
+		return err
+	}
+
+	tunnelAddr, err := service.TunnelAddr(endpoint)
+	if err != nil {
+		return err
+	}
+
+	requestURL := fmt.Sprintf("http://%s/ping", tunnelAddr)
+	req, err := http.NewRequest(http.MethodHead, requestURL, nil)
+	if err != nil {
+		return err
+	}
+
+	httpClient := &http.Client{
+		Timeout: pingTimeout,
+	}
+
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return err
+	}
+
+	_, _ = io.Copy(io.Discard, resp.Body)
+	return resp.Body.Close()
+}
+
+// KeepTunnelAlive keeps the tunnel of the given environment for maxAlive duration, or until ctx is done
+func (service *Service) KeepTunnelAlive(endpointID portainer.EndpointID, ctx context.Context, maxAlive time.Duration) {
+	go service.keepTunnelAlive(endpointID, ctx, maxAlive)
+}
+
+func (service *Service) keepTunnelAlive(endpointID portainer.EndpointID, ctx context.Context, maxAlive time.Duration) {
+	log.Debug().
+		Int("endpoint_id", int(endpointID)).
+		Float64("max_alive_minutes", maxAlive.Minutes()).
+		Msg("KeepTunnelAlive: start")
+
+	maxAliveTicker := time.NewTicker(maxAlive)
+	defer maxAliveTicker.Stop()
+
+	pingTicker := time.NewTicker(tunnelCleanupInterval)
+	defer pingTicker.Stop()
+
+	for {
+		select {
+		case <-pingTicker.C:
+			service.UpdateLastActivity(endpointID)
+
+			if err := service.pingAgent(endpointID); err != nil {
+				log.Debug().
+					Int("endpoint_id", int(endpointID)).
+					Err(err).
+					Msg("KeepTunnelAlive: ping agent")
+			}
+		case <-maxAliveTicker.C:
+			log.Debug().
+				Int("endpoint_id", int(endpointID)).
+				Float64("timeout_minutes", maxAlive.Minutes()).
+				Msg("KeepTunnelAlive: tunnel keep alive timeout")
+
+			return
+		case <-ctx.Done():
+			err := ctx.Err()
+			log.Debug().
+				Int("endpoint_id", int(endpointID)).
+				Err(err).
+				Msg("KeepTunnelAlive: tunnel stop")
+
+			return
+		}
+	}
+}
+
+// StartTunnelServer starts a tunnel server on the specified addr and port.
+// It uses a seed to generate a new private/public key pair. If the seed cannot
+// be found inside the database, it will generate a new one randomly and persist it.
+// It starts the tunnel status verification process in the background.
+// The snapshotter is used in the tunnel status verification process.
+func (service *Service) StartTunnelServer(addr, port string, snapshotService portainer.SnapshotService) error {
+	privateKeyFile, err := service.retrievePrivateKeyFile()
+	if err != nil {
+		return err
+	}
+
+	config := &chserver.Config{
+		Reverse:   true,
+		KeyFile:   privateKeyFile,
+		KeepAlive: tunnelKeepAliveInterval,
+	}
+
+	chiselServer, err := chserver.NewServer(config)
+	if err != nil {
+		return err
+	}
+
+	service.serverFingerprint = chiselServer.GetFingerprint()
+	service.serverPort = port
+
+	if err := chiselServer.Start(addr, port); err != nil {
+		return err
+	}
+
+	service.chiselServer = chiselServer
+
+	// TODO: work-around Chisel default behavior.
+	// By default, Chisel will allow anyone to connect if no user exists.
+	username, password := generateRandomCredentials()
+	if err = service.chiselServer.AddUser(username, password, "127.0.0.1"); err != nil {
+		return err
+	}
+
+	service.snapshotService = snapshotService
+
+	go service.startTunnelVerificationLoop()
+
+	return nil
+}
+
+// StopTunnelServer stops tunnel http server
+func (service *Service) StopTunnelServer() error {
+	return service.chiselServer.Close()
+}
+
+func (service *Service) retrievePrivateKeyFile() (string, error) {
+	privateKeyFile := service.fileService.GetDefaultChiselPrivateKeyPath()
+
+	if exists, _ := service.fileService.FileExists(privateKeyFile); exists {
+		log.Info().
+			Str("private-key", privateKeyFile).
+			Msg("found Chisel private key file on disk")
+
+		return privateKeyFile, nil
+	}
+
+	log.Debug().
+		Str("private-key", privateKeyFile).
+		Msg("chisel private key file does not exist")
+
+	privateKey, err := ccrypto.GenerateKey("")
+	if err != nil {
+		log.Error().
+			Err(err).
+			Msg("failed to generate chisel private key")
+
+		return "", err
+	}
+
+	if err = service.fileService.StoreChiselPrivateKey(privateKey); err != nil {
+		log.Error().
+			Err(err).
+			Msg("failed to save Chisel private key to disk")
+
+		return "", err
+	}
+
+	log.Info().
+		Str("private-key", privateKeyFile).
+		Msg("generated a new Chisel private key file")
+
+	return privateKeyFile, nil
+}
+
+func (service *Service) startTunnelVerificationLoop() {
+	log.Debug().
+		Float64("check_interval_seconds", tunnelCleanupInterval.Seconds()).
+		Msg("starting tunnel management process")
+
+	schedule.RunOnInterval(service.shutdownCtx, tunnelCleanupInterval, service.checkTunnels, func() {
+		log.Debug().Msg("shutting down tunnel service")
+
+		if err := service.StopTunnelServer(); err != nil {
+			log.Debug().Err(err).Msg("stopped tunnel service")
+		}
+	})
+}
+
+// checkTunnels finds tunnels that need snapshots and processes them one at a time.
+// For active tunnels missing an initial snapshot, it takes one without closing the tunnel.
+// For tunnels idle past activeTimeout, it snapshots and closes them.
+func (service *Service) checkTunnels() {
+	service.mu.RLock()
+
+	for endpointID, tunnel := range service.activeTunnels {
+		elapsed := time.Since(tunnel.LastActivity)
+		log.Debug().
+			Int("endpoint_id", int(endpointID)).
+			Float64("last_activity_seconds", elapsed.Seconds()).
+			Msg("environment tunnel monitoring")
+
+		tunnelPort := tunnel.Port
+
+		if !tunnel.HasSnapshot && elapsed < activeTimeout {
+			service.mu.RUnlock()
+
+			if endpointHasSnapshot(service.dataStore, endpointID) {
+				service.markSnapshotTaken(endpointID)
+
+				return
+			}
+
+			log.Debug().
+				Int("endpoint_id", int(endpointID)).
+				Msg("taking initial snapshot for active Edge environment")
+
+			if service.snapshotAndLog(endpointID, tunnelPort) {
+				service.markSnapshotTaken(endpointID)
+			}
+
+			return
+		}
+
+		if tunnel.Status == portainer.EdgeAgentManagementRequired && elapsed < activeTimeout {
+			continue
+		}
+
+		service.mu.RUnlock()
+
+		log.Debug().
+			Int("endpoint_id", int(endpointID)).
+			Float64("last_activity_seconds", elapsed.Seconds()).
+			Float64("timeout_seconds", activeTimeout.Seconds()).
+			Msg("last activity timeout exceeded")
+
+		service.snapshotAndLog(endpointID, tunnelPort)
+		service.close(endpointID)
+
+		return
+	}
+
+	service.mu.RUnlock()
+}
+
+func (service *Service) snapshotAndLog(endpointID portainer.EndpointID, tunnelPort int) bool {
+	if err := service.snapshotEnvironment(endpointID, tunnelPort); err != nil {
+		log.Error().
+			Int("endpoint_id", int(endpointID)).
+			Err(err).
+			Msg("unable to snapshot Edge environment")
+
+		if service.dataStore.IsErrObjectNotFound(err) {
+			service.close(endpointID)
+		}
+
+		return false
+	}
+
+	return true
+}
+
+func (service *Service) markSnapshotTaken(endpointID portainer.EndpointID) {
+	service.mu.Lock()
+	defer service.mu.Unlock()
+
+	if tun, ok := service.activeTunnels[endpointID]; ok {
+		tun.HasSnapshot = true
+	}
+}
+
+func (service *Service) snapshotEnvironment(endpointID portainer.EndpointID, tunnelPort int) error {
+	endpoint, err := service.dataStore.Endpoint().Endpoint(endpointID)
+	if err != nil {
+		return err
+	}
+
+	endpoint.URL = fmt.Sprintf("tcp://127.0.0.1:%d", tunnelPort)
+
+	return service.snapshotService.SnapshotEndpoint(endpoint)
+}

api/chisel/service_test.go

@@ -0,0 +1,238 @@
+package chisel
+
+import (
+	"context"
+	"errors"
+	"net"
+	"net/http"
+	"testing"
+	"time"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/datastore"
+	"github.com/portainer/portainer/pkg/fips"
+
+	"github.com/stretchr/testify/require"
+)
+
+func init() {
+	fips.InitFIPS(false)
+}
+
+type mockSnapshotService struct {
+	snapshotFn func(endpoint *portainer.Endpoint) error
+}
+
+func (m *mockSnapshotService) Start(_ context.Context) {}
+
+func (m *mockSnapshotService) SetSnapshotInterval(_ string) error { return nil }
+
+func (m *mockSnapshotService) SnapshotEndpoint(endpoint *portainer.Endpoint) error {
+	if m.snapshotFn != nil {
+		return m.snapshotFn(endpoint)
+	}
+
+	return nil
+}
+
+func (m *mockSnapshotService) FillSnapshotData(_ *portainer.Endpoint, _ bool) error { return nil }
+
+func newEdgeEndpoint(id portainer.EndpointID) *portainer.Endpoint {
+	return &portainer.Endpoint{
+		ID:          id,
+		EdgeID:      "test-edge-id",
+		Type:        portainer.EdgeAgentOnDockerEnvironment,
+		UserTrusted: true,
+	}
+}
+
+func TestPingAgentPanic(t *testing.T) {
+	t.Parallel()
+	endpoint := newEdgeEndpoint(1)
+
+	_, store := datastore.MustNewTestStore(t, false, true)
+
+	s := NewService(store, nil, nil)
+
+	defer func() {
+		require.Nil(t, recover())
+	}()
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/ping", func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(pingTimeout + 1*time.Second)
+	})
+
+	ln, err := net.ListenTCP("tcp", &net.TCPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 0})
+	require.NoError(t, err)
+
+	srv := &http.Server{Handler: mux}
+
+	errCh := make(chan error)
+	go func() {
+		errCh <- srv.Serve(ln)
+	}()
+
+	err = s.Open(endpoint)
+	require.NoError(t, err)
+	s.activeTunnels[endpoint.ID].Port = ln.Addr().(*net.TCPAddr).Port
+
+	require.Error(t, s.pingAgent(endpoint.ID))
+	require.NoError(t, srv.Shutdown(t.Context()))
+	require.ErrorIs(t, <-errCh, http.ErrServerClosed)
+}
+
+func TestOpenDefaultsHasSnapshotToFalse(t *testing.T) {
+	t.Parallel()
+
+	endpoint := newEdgeEndpoint(1)
+	_, store := datastore.MustNewTestStore(t, false, true)
+
+	s := NewService(store, nil, nil)
+
+	err := s.Open(endpoint)
+	require.NoError(t, err)
+
+	require.False(t, s.activeTunnels[endpoint.ID].HasSnapshot)
+}
+
+func TestCheckTunnelsSetsHasSnapshotWhenSnapshotExists(t *testing.T) {
+	t.Parallel()
+
+	endpoint := newEdgeEndpoint(2)
+	_, store := datastore.MustNewTestStore(t, false, true)
+
+	err := store.Endpoint().Create(endpoint)
+	require.NoError(t, err)
+
+	snap := &portainer.Snapshot{
+		EndpointID: endpoint.ID,
+		Docker:     &portainer.DockerSnapshot{},
+	}
+	err = store.Snapshot().Create(snap)
+	require.NoError(t, err)
+
+	s := NewService(store, nil, nil)
+	s.activeTunnels[endpoint.ID] = &portainer.TunnelDetails{
+		Status:       portainer.EdgeAgentManagementRequired,
+		Port:         50003,
+		LastActivity: time.Now(),
+	}
+
+	s.checkTunnels()
+
+	require.NotNil(t, s.activeTunnels[endpoint.ID], "tunnel must remain open")
+	require.True(t, s.activeTunnels[endpoint.ID].HasSnapshot)
+}
+
+func TestCheckTunnelsSnapshotsActiveEnvironmentAndKeepsTunnelAlive(t *testing.T) {
+	t.Parallel()
+
+	endpoint := newEdgeEndpoint(3)
+	_, store := datastore.MustNewTestStore(t, false, true)
+
+	err := store.Endpoint().Create(endpoint)
+	require.NoError(t, err)
+
+	snapshotCalled := false
+	svc := &mockSnapshotService{
+		snapshotFn: func(_ *portainer.Endpoint) error {
+			snapshotCalled = true
+
+			return nil
+		},
+	}
+
+	s := NewService(store, nil, nil)
+	s.snapshotService = svc
+	s.activeTunnels[endpoint.ID] = &portainer.TunnelDetails{
+		Status:       portainer.EdgeAgentManagementRequired,
+		Port:         50000,
+		LastActivity: time.Now(),
+	}
+
+	s.checkTunnels()
+
+	require.True(t, snapshotCalled)
+	require.NotNil(t, s.activeTunnels[endpoint.ID], "tunnel must remain open after snapshot")
+	require.True(t, s.activeTunnels[endpoint.ID].HasSnapshot)
+}
+
+func TestCheckTunnelsKeepsHasSnapshotFalseOnSnapshotFailure(t *testing.T) {
+	t.Parallel()
+
+	endpoint := newEdgeEndpoint(4)
+	_, store := datastore.MustNewTestStore(t, false, true)
+
+	err := store.Endpoint().Create(endpoint)
+	require.NoError(t, err)
+
+	svc := &mockSnapshotService{
+		snapshotFn: func(_ *portainer.Endpoint) error {
+			return errors.New("snapshot failed")
+		},
+	}
+
+	s := NewService(store, nil, nil)
+	s.snapshotService = svc
+	s.activeTunnels[endpoint.ID] = &portainer.TunnelDetails{
+		Status:       portainer.EdgeAgentManagementRequired,
+		Port:         50001,
+		LastActivity: time.Now(),
+	}
+
+	s.checkTunnels()
+
+	require.NotNil(t, s.activeTunnels[endpoint.ID], "tunnel must remain open after failed snapshot")
+	require.False(t, s.activeTunnels[endpoint.ID].HasSnapshot, "HasSnapshot must stay false after failure")
+}
+
+func TestCheckTunnelsClosesStaleEntryForDeletedEndpoint(t *testing.T) {
+	t.Parallel()
+
+	_, store := datastore.MustNewTestStore(t, false, true)
+
+	// Endpoint is not created in the store, simulates deletion while tunnel stays open.
+	s := NewService(store, nil, nil)
+	s.activeTunnels[1] = &portainer.TunnelDetails{
+		Status:       portainer.EdgeAgentManagementRequired,
+		Port:         50010,
+		LastActivity: time.Now(),
+	}
+
+	s.checkTunnels()
+
+	require.Nil(t, s.activeTunnels[1], "stale tunnel for deleted endpoint must be removed immediately")
+}
+
+func TestCheckTunnelsClosesIdleTunnelAndSnapshots(t *testing.T) {
+	t.Parallel()
+
+	endpoint := newEdgeEndpoint(5)
+	_, store := datastore.MustNewTestStore(t, false, true)
+
+	err := store.Endpoint().Create(endpoint)
+	require.NoError(t, err)
+
+	snapshotCalled := false
+	svc := &mockSnapshotService{
+		snapshotFn: func(_ *portainer.Endpoint) error {
+			snapshotCalled = true
+
+			return nil
+		},
+	}
+
+	s := NewService(store, nil, nil)
+	s.snapshotService = svc
+	s.activeTunnels[endpoint.ID] = &portainer.TunnelDetails{
+		Status:       portainer.EdgeAgentManagementRequired,
+		Port:         50002,
+		LastActivity: time.Now().Add(-(activeTimeout + time.Second)),
+	}
+
+	s.checkTunnels()
+
+	require.True(t, snapshotCalled)
+	require.Nil(t, s.activeTunnels[endpoint.ID], "tunnel must be closed after idle timeout")
+}

api/chisel/tunnel.go

@@ -0,0 +1,256 @@
+package chisel
+
+import (
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"net"
+	"strings"
+	"time"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+	"github.com/portainer/portainer/api/internal/edge"
+	"github.com/portainer/portainer/api/internal/edge/cache"
+	"github.com/portainer/portainer/api/internal/endpointutils"
+	"github.com/portainer/portainer/pkg/libcrypto"
+	"github.com/portainer/portainer/pkg/librand"
+
+	"github.com/dchest/uniuri"
+	"github.com/rs/zerolog/log"
+)
+
+const (
+	minAvailablePort = 49152
+	maxAvailablePort = 65535
+)
+
+var (
+	ErrNonEdgeEnv = errors.New("cannot open a tunnel for non-edge environments")
+	ErrAsyncEnv   = errors.New("cannot open a tunnel for async edge environments")
+	ErrInvalidEnv = errors.New("cannot open a tunnel for an invalid environment")
+)
+
+// Open will mark the tunnel as REQUIRED so the agent opens it
+func (s *Service) Open(endpoint *portainer.Endpoint) error {
+	if !endpointutils.IsEdgeEndpoint(endpoint) {
+		return ErrNonEdgeEnv
+	}
+
+	if endpoint.Edge.AsyncMode {
+		return ErrAsyncEnv
+	}
+
+	if endpoint.ID == 0 || endpoint.EdgeID == "" || !endpoint.UserTrusted {
+		return ErrInvalidEnv
+	}
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if _, ok := s.activeTunnels[endpoint.ID]; ok {
+		return nil
+	}
+
+	defer cache.Del(endpoint.ID)
+
+	tun := &portainer.TunnelDetails{
+		Status:       portainer.EdgeAgentManagementRequired,
+		Port:         s.getUnusedPort(),
+		LastActivity: time.Now(),
+	}
+
+	username, password := generateRandomCredentials()
+
+	if s.chiselServer != nil {
+		authorizedRemote := fmt.Sprintf("^R:0.0.0.0:%d$", tun.Port)
+
+		if err := s.chiselServer.AddUser(username, password, authorizedRemote); err != nil {
+			return err
+		}
+	}
+
+	credentials, err := encryptCredentials(username, password, endpoint.EdgeID)
+	if err != nil {
+		return err
+	}
+
+	tun.Credentials = credentials
+
+	s.activeTunnels[endpoint.ID] = tun
+
+	return nil
+}
+
+// close removes the tunnel from the map so the agent will close it.
+// The lock is released before cleaning up the chisel user and proxy to avoid
+// blocking Config/Open callers while DeleteUser interacts with chisel internals.
+func (s *Service) close(endpointID portainer.EndpointID) {
+	s.mu.Lock()
+
+	tun, ok := s.activeTunnels[endpointID]
+	if !ok {
+		s.mu.Unlock()
+		return
+	}
+
+	delete(s.activeTunnels, endpointID)
+	cache.Del(endpointID)
+
+	s.mu.Unlock()
+
+	if s.chiselServer != nil {
+		user, _, _ := strings.Cut(tun.Credentials, ":")
+		s.chiselServer.DeleteUser(user)
+	}
+
+	if s.ProxyManager != nil {
+		s.ProxyManager.DeleteEndpointProxy(endpointID)
+	}
+}
+
+// Config returns the tunnel details needed for the agent to connect
+func (s *Service) Config(endpointID portainer.EndpointID) portainer.TunnelDetails {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	if tun, ok := s.activeTunnels[endpointID]; ok {
+		return *tun
+	}
+
+	return portainer.TunnelDetails{Status: portainer.EdgeAgentIdle}
+}
+
+// TunnelAddr returns the address of the local tunnel, including the port, it
+// will block until the tunnel is ready
+func (s *Service) TunnelAddr(endpoint *portainer.Endpoint) (string, error) {
+	if err := s.Open(endpoint); err != nil {
+		return "", err
+	}
+
+	tun := s.Config(endpoint.ID)
+	checkinInterval := time.Duration(s.tryEffectiveCheckinInterval(endpoint)) * time.Second
+
+	for t0 := time.Now(); ; {
+		if time.Since(t0) > 2*checkinInterval {
+			return "", errors.New("unable to open the tunnel")
+		}
+
+		// Check if the tunnel is established
+		conn, err := net.DialTCP("tcp", nil, &net.TCPAddr{IP: net.IPv4(127, 0, 0, 1), Port: tun.Port})
+		if err != nil {
+			time.Sleep(checkinInterval / 100)
+
+			continue
+		}
+
+		if err := conn.Close(); err != nil {
+			log.Warn().Err(err).Msg("failed to close tcp connection")
+		}
+
+		break
+	}
+
+	s.UpdateLastActivity(endpoint.ID)
+
+	return fmt.Sprintf("127.0.0.1:%d", tun.Port), nil
+}
+
+// tryEffectiveCheckinInterval avoids a potential deadlock by returning a
+// previous known value after a timeout
+func (s *Service) tryEffectiveCheckinInterval(endpoint *portainer.Endpoint) int {
+	ch := make(chan int, 1)
+
+	go func() {
+		ch <- edge.EffectiveCheckinInterval(s.dataStore, endpoint)
+	}()
+
+	select {
+	case <-time.After(50 * time.Millisecond):
+		s.mu.RLock()
+		defer s.mu.RUnlock()
+
+		return s.defaultCheckinInterval
+	case i := <-ch:
+		s.mu.Lock()
+		s.defaultCheckinInterval = i
+		s.mu.Unlock()
+
+		return i
+	}
+}
+
+// UpdateLastActivity sets the current timestamp to avoid the tunnel timeout
+func (s *Service) UpdateLastActivity(endpointID portainer.EndpointID) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if tun, ok := s.activeTunnels[endpointID]; ok {
+		tun.LastActivity = time.Now()
+	}
+}
+
+// NOTE: it needs to be called with the lock acquired
+// getUnusedPort is used to generate an unused random port in the dynamic port range.
+// Dynamic ports (also called private ports) are 49152 to 65535.
+func (service *Service) getUnusedPort() int {
+	port := randomInt(minAvailablePort, maxAvailablePort)
+
+	for _, tunnel := range service.activeTunnels {
+		if tunnel.Port == port {
+			return service.getUnusedPort()
+		}
+	}
+
+	conn, err := net.DialTCP("tcp", nil, &net.TCPAddr{IP: net.IPv4(127, 0, 0, 1), Port: port})
+	if err == nil {
+		if err := conn.Close(); err != nil {
+			log.Warn().Msg("failed to close tcp connection that checks if port is free")
+		}
+
+		log.Debug().
+			Int("port", port).
+			Msg("selected port is in use, trying a different one")
+
+		return service.getUnusedPort()
+	}
+
+	return port
+}
+
+func randomInt(min, max int) int {
+	return min + librand.Intn(max-min)
+}
+
+func generateRandomCredentials() (string, string) {
+	username := uniuri.NewLen(8)
+	password := uniuri.NewLen(8)
+
+	return username, password
+}
+
+func encryptCredentials(username, password, key string) (string, error) {
+	credentials := fmt.Sprintf("%s:%s", username, password)
+
+	encryptedCredentials, err := libcrypto.Encrypt([]byte(credentials), []byte(key))
+	if err != nil {
+		return "", err
+	}
+
+	return base64.RawStdEncoding.EncodeToString(encryptedCredentials), nil
+}
+
+func endpointHasSnapshot(dataStore dataservices.DataStore, endpointID portainer.EndpointID) bool {
+	var hasSnapshot bool
+	_ = dataStore.ViewTx(func(tx dataservices.DataStoreTx) error {
+		s, err := tx.Snapshot().Read(endpointID)
+		if err != nil {
+			return err
+		}
+
+		hasSnapshot = s.Docker != nil || s.Kubernetes != nil
+		return nil
+	})
+
+	return hasSnapshot
+}

api/chisel/tunnel_test.go

@@ -0,0 +1,80 @@
+package chisel
+
+import (
+	"net"
+	"strings"
+	"testing"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+type testSettingsService struct {
+	dataservices.SettingsService
+}
+
+func (s *testSettingsService) Settings() (*portainer.Settings, error) {
+	return &portainer.Settings{
+		EdgeAgentCheckinInterval: 1,
+	}, nil
+}
+
+type testStore struct {
+	dataservices.DataStore
+}
+
+func (s *testStore) Settings() dataservices.SettingsService {
+	return &testSettingsService{}
+}
+
+func TestGetUnusedPort(t *testing.T) {
+	t.Parallel()
+	testCases := []struct {
+		name            string
+		existingTunnels map[portainer.EndpointID]*portainer.TunnelDetails
+		expectedError   error
+	}{
+		{
+			name: "simple case",
+		},
+		{
+			name: "existing tunnels",
+			existingTunnels: map[portainer.EndpointID]*portainer.TunnelDetails{
+				portainer.EndpointID(1): {
+					Port: 53072,
+				},
+				portainer.EndpointID(2): {
+					Port: 63072,
+				},
+			},
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			store := &testStore{}
+			s := NewService(store, nil, nil)
+			s.activeTunnels = tc.existingTunnels
+			port := s.getUnusedPort()
+
+			if port < 49152 || port > 65535 {
+				t.Fatalf("Expected port to be inbetween 49152 and 65535 but got %d", port)
+			}
+
+			for _, tun := range tc.existingTunnels {
+				if tun.Port == port {
+					t.Fatalf("returned port %d already has an existing tunnel", port)
+				}
+			}
+
+			conn, err := net.DialTCP("tcp", nil, &net.TCPAddr{IP: net.IPv4(127, 0, 0, 1), Port: port})
+			if err == nil {
+				// Ignore error
+				_ = conn.Close()
+				t.Fatalf("expected port %d to be unused", port)
+			} else if !strings.Contains(err.Error(), "connection refused") {
+				t.Fatalf("unexpected error: %v", err)
+			}
+		})
+	}
+}

api/cli/cli.go

@@ -0,0 +1,220 @@
+package cli
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	portainer "github.com/portainer/portainer/api"
+
+	"github.com/alecthomas/kingpin/v2"
+	"github.com/rs/zerolog/log"
+)
+
+// Service implements the CLIService interface
+type Service struct{}
+
+var (
+	ErrInvalidEndpointProtocol       = errors.New("Invalid environment protocol: Portainer only supports unix://, npipe:// or tcp://")
+	ErrSocketOrNamedPipeNotFound     = errors.New("Unable to locate Unix socket or named pipe")
+	ErrInvalidSnapshotInterval       = errors.New("Invalid snapshot interval")
+	ErrAdminPassExcludeAdminPassFile = errors.New("Cannot use --admin-password with --admin-password-file")
+)
+
+func CLIFlags() *portainer.CLIFlags {
+	return &portainer.CLIFlags{
+		Addr:                      kingpin.Flag("bind", "Address and port to serve Portainer").Default(defaultBindAddress).Short('p').String(),
+		AddrHTTPS:                 kingpin.Flag("bind-https", "Address and port to serve Portainer via https").Default(defaultHTTPSBindAddress).String(),
+		TunnelAddr:                kingpin.Flag("tunnel-addr", "Address to serve the tunnel server").Default(defaultTunnelServerAddress).String(),
+		TunnelPort:                kingpin.Flag("tunnel-port", "Port to serve the tunnel server").Default(defaultTunnelServerPort).String(),
+		Assets:                    kingpin.Flag("assets", "Path to the assets").Default(defaultAssetsDirectory).Short('a').String(),
+		Data:                      kingpin.Flag("data", "Path to the folder where the data is stored").Default(defaultDataDirectory).Short('d').String(),
+		EndpointURL:               kingpin.Flag("host", "Environment URL").Short('H').String(),
+		FeatureFlags:              kingpin.Flag("feat", "List of feature flags").Envar(portainer.FeatureFlagEnvVar).Strings(),
+		EnableEdgeComputeFeatures: kingpin.Flag("edge-compute", "Enable Edge Compute features").Bool(),
+		NoAnalytics:               kingpin.Flag("no-analytics", "Disable Analytics in app (deprecated)").Bool(),
+		TLSSkipVerify:             kingpin.Flag("tlsskipverify", "Disable TLS server verification").Default(defaultTLSSkipVerify).Bool(),
+		HTTPDisabled:              kingpin.Flag("http-disabled", "Serve portainer only on https").Default(defaultHTTPDisabled).Bool(),
+		HTTPEnabled:               kingpin.Flag("http-enabled", "Serve portainer on http").Default(defaultHTTPEnabled).Bool(),
+		Rollback:                  kingpin.Flag("rollback", "Rollback the database to the previous backup").Bool(),
+		SnapshotInterval:          kingpin.Flag("snapshot-interval", "Duration between each environment snapshot job").String(),
+		AdminPassword:             kingpin.Flag("admin-password", "Set admin password with provided hash").String(),
+		AdminPasswordFile:         kingpin.Flag("admin-password-file", "Path to the file containing the password for the admin user").String(),
+		Labels:                    pairs(kingpin.Flag("hide-label", "Hide containers with a specific label in the UI").Short('l')),
+		Logo:                      kingpin.Flag("logo", "URL for the logo displayed in the UI").String(),
+		Templates:                 kingpin.Flag("templates", "URL to the templates definitions.").Short('t').String(),
+		BaseURL:                   kingpin.Flag("base-url", "Base URL parameter such as portainer if running portainer as http://yourdomain.com/portainer/.").Short('b').Default(defaultBaseURL).String(),
+		InitialMmapSize:           kingpin.Flag("initial-mmap-size", "Initial mmap size of the database in bytes").Int(),
+		MaxBatchSize:              kingpin.Flag("max-batch-size", "Maximum size of a batch").Int(),
+		MaxBatchDelay:             kingpin.Flag("max-batch-delay", "Maximum delay before a batch starts").Duration(),
+		SecretKeyName:             kingpin.Flag("secret-key-name", "Secret key name for encryption and will be used as /run/secrets/<secret-key-name>.").Default(defaultSecretKeyName).String(),
+		LogLevel:                  kingpin.Flag("log-level", "Set the minimum logging level to show").Default("INFO").Enum("DEBUG", "INFO", "WARN", "ERROR"),
+		LogMode:                   kingpin.Flag("log-mode", "Set the logging output mode").Default("PRETTY").Enum("NOCOLOR", "PRETTY", "JSON"),
+		PullLimitCheckDisabled:    kingpin.Flag("pull-limit-check-disabled", "Pull limit check").Envar(portainer.PullLimitCheckDisabledEnvVar).Default(defaultPullLimitCheckDisabled).Bool(),
+		TrustedOrigins:            kingpin.Flag("trusted-origins", "List of trusted origins for CSRF protection. Separate multiple origins with a comma.").Envar(portainer.TrustedOriginsEnvVar).String(),
+		CSP:                       kingpin.Flag("csp", "Content Security Policy (CSP) header").Envar(portainer.CSPEnvVar).Default("true").Bool(),
+		CompactDB:                 kingpin.Flag("compact-db", "Enable database compaction on startup").Envar(portainer.CompactDBEnvVar).Default("false").Bool(),
+		NoSetupToken:              kingpin.Flag("no-setup-token", "Disable the setup token requirement for admin initialization and restore on an uninitialized instance").Envar(portainer.NoSetupTokenEnvVar).Bool(),
+		SetupToken:                kingpin.Flag("setup-token", "Set a custom setup token for admin initialization and restore on an uninitialized instance (overrides auto-generation)").Envar(portainer.SetupTokenEnvVar).String(),
+	}
+}
+
+// ParseFlags parse the CLI flags and return a portainer.Flags struct
+func (Service) ParseFlags(version string) (*portainer.CLIFlags, error) {
+	kingpin.Version(version)
+
+	var hasSSLFlag, hasSSLCertFlag, hasSSLKeyFlag bool
+	sslFlag := kingpin.Flag(
+		"ssl",
+		"Secure Portainer instance using SSL (deprecated)",
+	).Default(defaultSSL).IsSetByUser(&hasSSLFlag)
+	ssl := sslFlag.Bool()
+	sslCertFlag := kingpin.Flag(
+		"sslcert",
+		"Path to the SSL certificate used to secure the Portainer instance",
+	).IsSetByUser(&hasSSLCertFlag)
+	sslCert := sslCertFlag.String()
+	sslKeyFlag := kingpin.Flag(
+		"sslkey",
+		"Path to the SSL key used to secure the Portainer instance",
+	).IsSetByUser(&hasSSLKeyFlag)
+	sslKey := sslKeyFlag.String()
+
+	flags := CLIFlags()
+
+	var hasTLSFlag, hasTLSCertFlag, hasTLSKeyFlag bool
+	tlsFlag := kingpin.Flag("tlsverify", "TLS support").Default(defaultTLS).IsSetByUser(&hasTLSFlag)
+	flags.TLS = tlsFlag.Bool()
+	tlsCertFlag := kingpin.Flag(
+		"tlscert",
+		"Path to the TLS certificate file",
+	).Default(defaultTLSCertPath).IsSetByUser(&hasTLSCertFlag)
+	flags.TLSCert = tlsCertFlag.String()
+	tlsKeyFlag := kingpin.Flag("tlskey", "Path to the TLS key").Default(defaultTLSKeyPath).IsSetByUser(&hasTLSKeyFlag)
+	flags.TLSKey = tlsKeyFlag.String()
+	flags.TLSCacert = kingpin.Flag("tlscacert", "Path to the CA").Default(defaultTLSCACertPath).String()
+
+	var hasKubectlShellImageFlag bool
+	kubectlShellImageFlag := kingpin.Flag(
+		"kubectl-shell-image",
+		"Kubectl shell image",
+	).Envar(portainer.KubectlShellImageEnvVar).
+		Default(portainer.DefaultKubectlShellImage).
+		IsSetByUser(&hasKubectlShellImageFlag)
+	flags.KubectlShellImage = kubectlShellImageFlag.String()
+
+	kingpin.Parse()
+
+	_, kubectlShellImageEnvVarSet := os.LookupEnv(portainer.KubectlShellImageEnvVar)
+	flags.KubectlShellImageSet = hasKubectlShellImageFlag || kubectlShellImageEnvVarSet
+
+	if !filepath.IsAbs(*flags.Assets) {
+		ex, err := os.Executable()
+		if err != nil {
+			panic(err)
+		}
+
+		*flags.Assets = filepath.Join(filepath.Dir(ex), *flags.Assets)
+	}
+
+	// If the user didn't provide a tls flag remove the defaults to match previous behaviour
+	if !hasTLSFlag {
+		if !hasTLSCertFlag {
+			*flags.TLSCert = ""
+		}
+
+		if !hasTLSKeyFlag {
+			*flags.TLSKey = ""
+		}
+	}
+
+	if hasSSLFlag {
+		log.Warn().Msgf("the %q flag is deprecated. use %q instead.", sslFlag.Model().Name, tlsFlag.Model().Name)
+
+		if !hasTLSFlag {
+			flags.TLS = ssl
+		}
+	}
+
+	if hasSSLCertFlag {
+		log.Warn().Msgf("the %q flag is deprecated. use %q instead.", sslCertFlag.Model().Name, tlsCertFlag.Model().Name)
+
+		if !hasTLSCertFlag {
+			flags.TLSCert = sslCert
+		}
+	}
+
+	if hasSSLKeyFlag {
+		log.Warn().Msgf("the %q flag is deprecated. use %q instead.", sslKeyFlag.Model().Name, tlsKeyFlag.Model().Name)
+
+		if !hasTLSKeyFlag {
+			flags.TLSKey = sslKey
+		}
+	}
+
+	return flags, nil
+}
+
+// ValidateFlags validates the values of the flags.
+func (Service) ValidateFlags(flags *portainer.CLIFlags) error {
+	displayDeprecationWarnings(flags)
+
+	if err := ValidateEndpointURL(*flags.EndpointURL); err != nil {
+		return err
+	}
+
+	if err := ValidateSnapshotInterval(*flags.SnapshotInterval); err != nil {
+		return err
+	}
+
+	if *flags.AdminPassword != "" && *flags.AdminPasswordFile != "" {
+		return ErrAdminPassExcludeAdminPassFile
+	}
+
+	return nil
+}
+
+func displayDeprecationWarnings(flags *portainer.CLIFlags) {
+	if *flags.NoAnalytics {
+		log.Warn().Msg("the --no-analytics flag has been kept to allow migration of instances running a previous version of Portainer with this flag enabled, to version 2.0 where enabling this flag will have no effect")
+	}
+}
+
+func ValidateEndpointURL(endpointURL string) error {
+	if endpointURL == "" {
+		return nil
+	}
+
+	if !strings.HasPrefix(endpointURL, "unix://") && !strings.HasPrefix(endpointURL, "tcp://") && !strings.HasPrefix(endpointURL, "npipe://") {
+		return ErrInvalidEndpointProtocol
+	}
+
+	if strings.HasPrefix(endpointURL, "unix://") || strings.HasPrefix(endpointURL, "npipe://") {
+		socketPath := strings.TrimPrefix(endpointURL, "unix://")
+		socketPath = strings.TrimPrefix(socketPath, "npipe://")
+
+		if _, err := os.Stat(socketPath); err != nil {
+			if os.IsNotExist(err) {
+				return ErrSocketOrNamedPipeNotFound
+			}
+
+			return err
+		}
+	}
+
+	return nil
+}
+
+func ValidateSnapshotInterval(snapshotInterval string) error {
+	if snapshotInterval == "" {
+		return nil
+	}
+
+	if _, err := time.ParseDuration(snapshotInterval); err != nil {
+		return ErrInvalidSnapshotInterval
+	}
+
+	return nil
+}

api/cli/cli_test.go

@@ -0,0 +1,263 @@
+package cli
+
+import (
+	"io"
+	"os"
+	"strings"
+	"testing"
+
+	portainer "github.com/portainer/portainer/api"
+	zerolog "github.com/rs/zerolog/log"
+	"github.com/stretchr/testify/require"
+)
+
+func TestOptionParser(t *testing.T) {
+	p := Service{}
+	require.NotNil(t, p)
+
+	a := os.Args
+	defer func() { os.Args = a }()
+
+	os.Args = []string{"portainer", "--edge-compute"}
+
+	opts, err := p.ParseFlags("2.34.5")
+	require.NoError(t, err)
+
+	require.False(t, *opts.HTTPDisabled)
+	require.True(t, *opts.EnableEdgeComputeFeatures)
+}
+
+func TestParseKubectlShellImageFlag(t *testing.T) {
+	tests := []struct {
+		name                         string
+		args                         []string
+		envVars                      map[string]string
+		expectedKubectlShellImageSet bool
+		expectedKubectlShellFlag     string
+	}{
+		{
+			name:                         "no flag, no env var",
+			expectedKubectlShellImageSet: false,
+			expectedKubectlShellFlag:     portainer.DefaultKubectlShellImage,
+		},
+		{
+			name:                         "explicit flag",
+			args:                         []string{"portainer", "--kubectl-shell-image=myimage:v2"},
+			expectedKubectlShellImageSet: true,
+			expectedKubectlShellFlag:     "myimage:v2",
+		},
+		{
+			name:                         "env var",
+			envVars:                      map[string]string{portainer.KubectlShellImageEnvVar: "myimage:v3"},
+			expectedKubectlShellImageSet: true,
+			expectedKubectlShellFlag:     "myimage:v3",
+		},
+		{
+			name:                         "both env var and flag set",
+			args:                         []string{"portainer", "--kubectl-shell-image=myimage:v2"},
+			envVars:                      map[string]string{portainer.KubectlShellImageEnvVar: "myimage:v3"},
+			expectedKubectlShellImageSet: true,
+			expectedKubectlShellFlag:     "myimage:v2",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if tc.args == nil {
+				tc.args = []string{"portainer"}
+			}
+			setOsArgs(t, tc.args)
+
+			for k, v := range tc.envVars {
+				t.Setenv(k, v)
+			}
+
+			flags, err := Service{}.ParseFlags("test-version")
+			require.NoError(t, err)
+			require.Equal(t, tc.expectedKubectlShellImageSet, flags.KubectlShellImageSet)
+			require.Equal(t, tc.expectedKubectlShellFlag, *flags.KubectlShellImage)
+		})
+	}
+}
+
+func TestParseTLSFlags(t *testing.T) {
+	testCases := []struct {
+		name                string
+		args                []string
+		expectedTLSFlag     bool
+		expectedTLSCertFlag string
+		expectedTLSKeyFlag  string
+		expectedLogMessages []string
+	}{
+		{
+			name:                "no flags",
+			expectedTLSFlag:     false,
+			expectedTLSCertFlag: "",
+			expectedTLSKeyFlag:  "",
+		},
+		{
+			name: "only ssl flag",
+			args: []string{
+				"portainer",
+				"--ssl",
+			},
+			expectedTLSFlag:     true,
+			expectedTLSCertFlag: "",
+			expectedTLSKeyFlag:  "",
+		},
+		{
+			name: "only tls flag",
+			args: []string{
+				"portainer",
+				"--tlsverify",
+			},
+			expectedTLSFlag:     true,
+			expectedTLSCertFlag: defaultTLSCertPath,
+			expectedTLSKeyFlag:  defaultTLSKeyPath,
+		},
+		{
+			name: "partial ssl flags",
+			args: []string{
+				"portainer",
+				"--ssl",
+				"--sslcert=ssl-cert-flag-value",
+			},
+			expectedTLSFlag:     true,
+			expectedTLSCertFlag: "ssl-cert-flag-value",
+			expectedTLSKeyFlag:  "",
+		},
+		{
+			name: "partial tls flags",
+			args: []string{
+				"portainer",
+				"--tlsverify",
+				"--tlscert=tls-cert-flag-value",
+			},
+			expectedTLSFlag:     true,
+			expectedTLSCertFlag: "tls-cert-flag-value",
+			expectedTLSKeyFlag:  defaultTLSKeyPath,
+		},
+		{
+			name: "partial tls and ssl flags",
+			args: []string{
+				"portainer",
+				"--tlsverify",
+				"--tlscert=tls-cert-flag-value",
+				"--sslkey=ssl-key-flag-value",
+			},
+			expectedTLSFlag:     true,
+			expectedTLSCertFlag: "tls-cert-flag-value",
+			expectedTLSKeyFlag:  "ssl-key-flag-value",
+		},
+		{
+			name: "partial tls and ssl flags 2",
+			args: []string{
+				"portainer",
+				"--ssl",
+				"--tlscert=tls-cert-flag-value",
+				"--sslkey=ssl-key-flag-value",
+			},
+			expectedTLSFlag:     true,
+			expectedTLSCertFlag: "tls-cert-flag-value",
+			expectedTLSKeyFlag:  "ssl-key-flag-value",
+		},
+		{
+			name: "ssl flags",
+			args: []string{
+				"portainer",
+				"--ssl",
+				"--sslcert=ssl-cert-flag-value",
+				"--sslkey=ssl-key-flag-value",
+			},
+			expectedTLSFlag:     true,
+			expectedTLSCertFlag: "ssl-cert-flag-value",
+			expectedTLSKeyFlag:  "ssl-key-flag-value",
+			expectedLogMessages: []string{
+				"the \\\"ssl\\\" flag is deprecated. use \\\"tlsverify\\\" instead.",
+				"the \\\"sslcert\\\" flag is deprecated. use \\\"tlscert\\\" instead.",
+				"the \\\"sslkey\\\" flag is deprecated. use \\\"tlskey\\\" instead.",
+			},
+		},
+		{
+			name: "tls flags",
+			args: []string{
+				"portainer",
+				"--tlsverify",
+				"--tlscert=tls-cert-flag-value",
+				"--tlskey=tls-key-flag-value",
+			},
+			expectedTLSFlag:     true,
+			expectedTLSCertFlag: "tls-cert-flag-value",
+			expectedTLSKeyFlag:  "tls-key-flag-value",
+		},
+		{
+			name: "tls and ssl flags",
+			args: []string{
+				"portainer",
+				"--tlsverify",
+				"--tlscert=tls-cert-flag-value",
+				"--tlskey=tls-key-flag-value",
+				"--ssl",
+				"--sslcert=ssl-cert-flag-value",
+				"--sslkey=ssl-key-flag-value",
+			},
+			expectedTLSFlag:     true,
+			expectedTLSCertFlag: "tls-cert-flag-value",
+			expectedTLSKeyFlag:  "tls-key-flag-value",
+			expectedLogMessages: []string{
+				"the \\\"ssl\\\" flag is deprecated. use \\\"tlsverify\\\" instead.",
+				"the \\\"sslcert\\\" flag is deprecated. use \\\"tlscert\\\" instead.",
+				"the \\\"sslkey\\\" flag is deprecated. use \\\"tlskey\\\" instead.",
+			},
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			var logOutput strings.Builder
+			setupLogOutput(t, &logOutput)
+
+			if tc.args == nil {
+				tc.args = []string{"portainer"}
+			}
+			setOsArgs(t, tc.args)
+
+			s := Service{}
+			flags, err := s.ParseFlags("test-version")
+			if err != nil {
+				t.Fatalf("error parsing flags: %v", err)
+			}
+
+			if flags.TLS == nil {
+				t.Fatal("TLS flag was nil")
+			}
+
+			require.Equal(t, tc.expectedTLSFlag, *flags.TLS, "tlsverify flag didn't match")
+			require.Equal(t, tc.expectedTLSCertFlag, *flags.TLSCert, "tlscert flag didn't match")
+			require.Equal(t, tc.expectedTLSKeyFlag, *flags.TLSKey, "tlskey flag didn't match")
+
+			for _, expectedLogMessage := range tc.expectedLogMessages {
+				require.Contains(t, logOutput.String(), expectedLogMessage, "Log didn't contain expected message")
+			}
+		})
+	}
+}
+
+func setOsArgs(t *testing.T, args []string) {
+	t.Helper()
+	previousArgs := os.Args
+	os.Args = args
+	t.Cleanup(func() {
+		os.Args = previousArgs
+	})
+}
+
+func setupLogOutput(t *testing.T, w io.Writer) {
+	t.Helper()
+
+	oldLogger := zerolog.Logger
+	zerolog.Logger = zerolog.Output(w)
+	t.Cleanup(func() {
+		zerolog.Logger = oldLogger
+	})
+}

api/cli/confirm.go

@@ -0,0 +1,23 @@
+package cli
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"strings"
+)
+
+// Confirm starts a rollback db cli application
+func Confirm(message string) (bool, error) {
+	fmt.Printf("%s [y/N] ", message)
+
+	reader := bufio.NewReader(os.Stdin)
+
+	answer, err := reader.ReadString('\n')
+	if err != nil {
+		return false, err
+	}
+
+	answer = strings.ReplaceAll(answer, "\n", "")
+	return strings.EqualFold(answer, "y") || strings.EqualFold(answer, "yes"), nil
+}

api/cli/defaults.go

@@ -0,0 +1,23 @@
+//go:build !windows
+
+package cli
+
+const (
+	defaultBindAddress            = ":9000"
+	defaultHTTPSBindAddress       = ":9443"
+	defaultTunnelServerAddress    = "0.0.0.0"
+	defaultTunnelServerPort       = "8000"
+	defaultDataDirectory          = "/data"
+	defaultAssetsDirectory        = "./"
+	defaultTLS                    = "false"
+	defaultTLSSkipVerify          = "false"
+	defaultTLSCACertPath          = "/certs/ca.pem"
+	defaultTLSCertPath            = "/certs/cert.pem"
+	defaultTLSKeyPath             = "/certs/key.pem"
+	defaultHTTPDisabled           = "false"
+	defaultHTTPEnabled            = "false"
+	defaultSSL                    = "false"
+	defaultBaseURL                = "/"
+	defaultSecretKeyName          = "portainer"
+	defaultPullLimitCheckDisabled = "false"
+)

api/cli/defaults_windows.go

@@ -0,0 +1,22 @@
+package cli
+
+const (
+	defaultBindAddress            = ":9000"
+	defaultHTTPSBindAddress       = ":9443"
+	defaultTunnelServerAddress    = "0.0.0.0"
+	defaultTunnelServerPort       = "8000"
+	defaultDataDirectory          = "C:\\data"
+	defaultAssetsDirectory        = "./"
+	defaultTLS                    = "false"
+	defaultTLSSkipVerify          = "false"
+	defaultTLSCACertPath          = "C:\\certs\\ca.pem"
+	defaultTLSCertPath            = "C:\\certs\\cert.pem"
+	defaultTLSKeyPath             = "C:\\certs\\key.pem"
+	defaultHTTPDisabled           = "false"
+	defaultHTTPEnabled            = "false"
+	defaultSSL                    = "false"
+	defaultSnapshotInterval       = "5m"
+	defaultBaseURL                = "/"
+	defaultSecretKeyName          = "portainer"
+	defaultPullLimitCheckDisabled = "false"
+)

api/cli/pairlist.go

@@ -0,0 +1,41 @@
+package cli
+
+import (
+	portainer "github.com/portainer/portainer/api"
+
+	"fmt"
+	"strings"
+
+	"github.com/alecthomas/kingpin/v2"
+)
+
+type pairList []portainer.Pair
+
+// Set implementation for a list of portainer.Pair
+func (l *pairList) Set(value string) error {
+	parts := strings.SplitN(value, "=", 2)
+	if len(parts) != 2 {
+		return fmt.Errorf("expected NAME=VALUE got '%s'", value)
+	}
+	p := new(portainer.Pair)
+	p.Name = parts[0]
+	p.Value = parts[1]
+	*l = append(*l, *p)
+	return nil
+}
+
+// String implementation for a list of pair
+func (l *pairList) String() string {
+	return ""
+}
+
+// IsCumulative implementation for a list of pair
+func (l *pairList) IsCumulative() bool {
+	return true
+}
+
+func pairs(s kingpin.Settings) (target *[]portainer.Pair) {
+	target = new([]portainer.Pair)
+	s.SetValue((*pairList)(target))
+	return
+}

api/cmd/portainer/main.go

@@ -0,0 +1,728 @@
+package main
+
+import (
+	"cmp"
+	"context"
+	"crypto/sha256"
+	nethttp "net/http"
+	"os"
+	"path"
+	"strings"
+	"time"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/apikey"
+	"github.com/portainer/portainer/api/chisel"
+	"github.com/portainer/portainer/api/cli"
+	"github.com/portainer/portainer/api/crypto"
+	"github.com/portainer/portainer/api/database"
+	"github.com/portainer/portainer/api/database/boltdb"
+	"github.com/portainer/portainer/api/database/models"
+	"github.com/portainer/portainer/api/dataservices"
+	"github.com/portainer/portainer/api/datastore"
+	"github.com/portainer/portainer/api/datastore/migrator"
+	"github.com/portainer/portainer/api/datastore/postinit"
+	"github.com/portainer/portainer/api/docker"
+	dockerclient "github.com/portainer/portainer/api/docker/client"
+	"github.com/portainer/portainer/api/exec"
+	"github.com/portainer/portainer/api/filesystem"
+	"github.com/portainer/portainer/api/git"
+	"github.com/portainer/portainer/api/http"
+	"github.com/portainer/portainer/api/http/proxy"
+	kubeproxy "github.com/portainer/portainer/api/http/proxy/factory/kubernetes"
+	"github.com/portainer/portainer/api/http/security/setuptoken"
+	"github.com/portainer/portainer/api/internal/authorization"
+	"github.com/portainer/portainer/api/internal/edge/edgestacks"
+	"github.com/portainer/portainer/api/internal/endpointutils"
+	"github.com/portainer/portainer/api/internal/snapshot"
+	"github.com/portainer/portainer/api/internal/ssl"
+	"github.com/portainer/portainer/api/internal/upgrade"
+	"github.com/portainer/portainer/api/jwt"
+	"github.com/portainer/portainer/api/kubernetes"
+	kubecli "github.com/portainer/portainer/api/kubernetes/cli"
+	"github.com/portainer/portainer/api/ldap"
+	"github.com/portainer/portainer/api/logs"
+	"github.com/portainer/portainer/api/oauth"
+	"github.com/portainer/portainer/api/pendingactions"
+	"github.com/portainer/portainer/api/pendingactions/actions"
+	"github.com/portainer/portainer/api/pendingactions/handlers"
+	"github.com/portainer/portainer/api/platform"
+	"github.com/portainer/portainer/api/scheduler"
+	"github.com/portainer/portainer/api/stacks/deployments"
+	"github.com/portainer/portainer/pkg/build"
+	"github.com/portainer/portainer/pkg/featureflags"
+	"github.com/portainer/portainer/pkg/fips"
+	"github.com/portainer/portainer/pkg/libhelm"
+	"github.com/portainer/portainer/pkg/libhttp/ssrf"
+	"github.com/portainer/portainer/pkg/libstack/compose"
+	libswarm "github.com/portainer/portainer/pkg/libstack/swarm"
+	"github.com/portainer/portainer/pkg/validate"
+
+	gogitclient "github.com/go-git/go-git/v5/plumbing/transport/client"
+	gogitraw "github.com/go-git/go-git/v5/plumbing/transport/git"
+	gogithttp "github.com/go-git/go-git/v5/plumbing/transport/http"
+	gogitssh "github.com/go-git/go-git/v5/plumbing/transport/ssh"
+	"github.com/google/uuid"
+	"github.com/rs/zerolog/log"
+)
+
+func initCLI() *portainer.CLIFlags {
+	cliService := cli.Service{}
+
+	flags, err := cliService.ParseFlags(portainer.APIVersion)
+	if err != nil {
+		log.Fatal().Err(err).Msg("failed parsing flags")
+	}
+
+	if err := cliService.ValidateFlags(flags); err != nil {
+		log.Fatal().Err(err).Msg("failed validating flags")
+	}
+
+	return flags
+}
+
+func initFileService(dataStorePath string) portainer.FileService {
+	fileService, err := filesystem.NewService(dataStorePath, "")
+	if err != nil {
+		log.Fatal().Err(err).Msg("failed creating file service")
+	}
+
+	return fileService
+}
+
+func initDataStore(flags *portainer.CLIFlags, secretKey []byte, fileService portainer.FileService, shutdownCtx context.Context) dataservices.DataStore {
+	connection, err := database.NewDatabase("boltdb", *flags.Data, secretKey, *flags.CompactDB)
+	if err != nil {
+		log.Fatal().Err(err).Msg("failed creating database connection")
+	}
+
+	if bconn, ok := connection.(*boltdb.DbConnection); ok {
+		bconn.MaxBatchSize = *flags.MaxBatchSize
+		bconn.MaxBatchDelay = *flags.MaxBatchDelay
+		bconn.InitialMmapSize = *flags.InitialMmapSize
+	} else {
+		log.Fatal().Msg("failed creating database connection: expecting a boltdb database type but a different one was received")
+	}
+
+	store := datastore.NewStore(flags, fileService, connection)
+
+	isNew, err := store.Open()
+	if err != nil {
+		log.Fatal().Err(err).Msg("failed opening store")
+	}
+
+	if *flags.Rollback {
+		if err := store.Rollback(false); err != nil {
+			log.Fatal().Err(err).Msg("failed rolling back")
+		}
+
+		log.Info().Msg("exiting rollback")
+		os.Exit(0)
+	}
+
+	// Init sets some defaults - it's basically a migration
+	if err := store.Init(); err != nil {
+		log.Fatal().Err(err).Msg("failed initializing data store")
+	}
+
+	if isNew {
+		instanceId, err := uuid.NewRandom()
+		if err != nil {
+			log.Fatal().Err(err).Msg("failed generating instance id")
+		}
+
+		migratorInstance := migrator.NewMigrator(&migrator.MigratorParameters{Flags: flags})
+		migratorCount := migratorInstance.GetMigratorCountOfCurrentAPIVersion()
+
+		// from MigrateData
+		v := models.Version{
+			SchemaVersion: portainer.APIVersion,
+			Edition:       int(portainer.PortainerCE),
+			InstanceID:    instanceId.String(),
+			MigratorCount: migratorCount,
+		}
+
+		if err := store.VersionService.UpdateVersion(&v); err != nil {
+			log.Fatal().Err(err).Msg("failed to update version")
+		}
+
+		if err := updateSettingsFromFlags(store, flags); err != nil {
+			log.Fatal().Err(err).Msg("failed updating settings from flags")
+		}
+	} else if err := store.MigrateData(); err != nil {
+		log.Fatal().Err(err).Msg("failed migration")
+	}
+
+	if err := updateSettingsFromFlags(store, flags); err != nil {
+		log.Fatal().Err(err).Msg("failed updating settings from flags")
+	}
+
+	// this is for the db restore functionality - needs more tests.
+	go func() {
+		<-shutdownCtx.Done()
+
+		defer logs.CloseAndLogErr(connection)
+	}()
+
+	return store
+}
+
+// checkDBSchemaServerVersionMatch checks if the server version matches the db scehma version
+func checkDBSchemaServerVersionMatch(dbStore dataservices.DataStore, serverVersion string, serverEdition int) bool {
+	v, err := dbStore.Version().Version()
+	if err != nil {
+		return false
+	}
+
+	return v.SchemaVersion == serverVersion && v.Edition == serverEdition
+}
+
+func initKubernetesDeployer(kubernetesTokenCacheManager *kubeproxy.TokenCacheManager, kubernetesClientFactory *kubecli.ClientFactory, dataStore dataservices.DataStore, reverseTunnelService portainer.ReverseTunnelService, signatureService portainer.DigitalSignatureService, proxyManager *proxy.Manager) portainer.KubernetesDeployer {
+	return exec.NewKubernetesDeployer(kubernetesTokenCacheManager, kubernetesClientFactory, dataStore, reverseTunnelService, signatureService, proxyManager)
+}
+
+func initAPIKeyService(datastore dataservices.DataStore) apikey.APIKeyService {
+	return apikey.NewAPIKeyService(datastore.APIKeyRepository(), datastore.User())
+}
+
+func initJWTService(userSessionTimeout string, dataStore dataservices.DataStore) (portainer.JWTService, error) {
+	if userSessionTimeout == "" {
+		userSessionTimeout = portainer.DefaultUserSessionTimeout
+	}
+
+	return jwt.NewService(userSessionTimeout, dataStore)
+}
+
+func initDigitalSignatureService() portainer.DigitalSignatureService {
+	return crypto.NewECDSAService(os.Getenv("AGENT_SECRET"))
+}
+
+func initSSLService(addr, certPath, keyPath string, fileService portainer.FileService, dataStore dataservices.DataStore, shutdownTrigger context.CancelFunc) (*ssl.Service, error) {
+	slices := strings.Split(addr, ":")
+
+	host := slices[0]
+	if host == "" {
+		host = "0.0.0.0"
+	}
+
+	sslService := ssl.NewService(fileService, dataStore, shutdownTrigger)
+
+	if err := sslService.Init(host, certPath, keyPath); err != nil {
+		return nil, err
+	}
+
+	return sslService, nil
+}
+
+func initSnapshotService(
+	snapshotIntervalFromFlag string,
+	dataStore dataservices.DataStore,
+	dockerClientFactory *dockerclient.ClientFactory,
+	kubernetesClientFactory *kubecli.ClientFactory,
+	pendingActionsService *pendingactions.PendingActionsService,
+) (portainer.SnapshotService, error) {
+	dockerSnapshotter := docker.NewSnapshotter(dockerClientFactory)
+	kubernetesSnapshotter := kubernetes.NewSnapshotter(kubernetesClientFactory)
+
+	snapshotService, err := snapshot.NewService(snapshotIntervalFromFlag, dataStore, dockerSnapshotter, kubernetesSnapshotter, pendingActionsService)
+	if err != nil {
+		return nil, err
+	}
+
+	return snapshotService, nil
+}
+
+func resolveSetupToken(tx dataservices.DataStoreTx, providedToken string) (string, error) {
+	admins, err := tx.User().UsersByRole(portainer.AdministratorRole)
+	if err != nil {
+		return "", err
+	}
+	if len(admins) > 0 {
+		return "", nil
+	}
+
+	if providedToken != "" {
+		log.Info().Msg("using custom setup token; admin initialization and backup restore require this token in the X-Setup-Token header")
+		return providedToken, nil
+	}
+
+	token, err := setuptoken.Generate()
+	if err != nil {
+		return "", err
+	}
+
+	log.Info().
+		Str("setup_token", token).
+		Msg("no administrator account configured; admin initialization and backup restore require this setup token in the X-Setup-Token header. Start with --no-setup-token to disable.")
+
+	return token, nil
+}
+
+func initStatus(instanceID string) *portainer.Status {
+	return &portainer.Status{
+		Version:    portainer.APIVersion,
+		InstanceID: instanceID,
+	}
+}
+
+func updateSettingsFromFlags(dataStore dataservices.DataStore, flags *portainer.CLIFlags) error {
+	settings, err := dataStore.Settings().Settings()
+	if err != nil {
+		return err
+	}
+
+	settings.SnapshotInterval = cmp.Or(*flags.SnapshotInterval, settings.SnapshotInterval)
+	settings.LogoURL = cmp.Or(*flags.Logo, settings.LogoURL)
+	settings.EnableEdgeComputeFeatures = cmp.Or(*flags.EnableEdgeComputeFeatures, settings.EnableEdgeComputeFeatures)
+	settings.TemplatesURL = cmp.Or(*flags.Templates, settings.TemplatesURL)
+
+	if flags.KubectlShellImageSet {
+		settings.KubectlShellImage = *flags.KubectlShellImage
+	}
+
+	if *flags.Labels != nil {
+		settings.BlackListedLabels = *flags.Labels
+	}
+
+	settings.AgentSecret = ""
+	if agentKey, ok := os.LookupEnv("AGENT_SECRET"); ok {
+		settings.AgentSecret = agentKey
+	}
+
+	if err := dataStore.Settings().UpdateSettings(settings); err != nil {
+		return err
+	}
+
+	sslSettings, err := dataStore.SSLSettings().Settings()
+	if err != nil {
+		return err
+	}
+
+	if *flags.HTTPDisabled {
+		sslSettings.HTTPEnabled = false
+	} else if *flags.HTTPEnabled {
+		sslSettings.HTTPEnabled = true
+	}
+
+	return dataStore.SSLSettings().UpdateSettings(sslSettings)
+}
+
+func loadAndParseKeyPair(fileService portainer.FileService, signatureService portainer.DigitalSignatureService) error {
+	private, public, err := fileService.LoadKeyPair()
+	if err != nil {
+		return err
+	}
+
+	return signatureService.ParseKeyPair(private, public)
+}
+
+func generateAndStoreKeyPair(fileService portainer.FileService, signatureService portainer.DigitalSignatureService) error {
+	private, public, err := signatureService.GenerateKeyPair()
+	if err != nil {
+		return err
+	}
+
+	privateHeader, publicHeader := signatureService.PEMHeaders()
+
+	return fileService.StoreKeyPair(private, public, privateHeader, publicHeader)
+}
+
+func initKeyPair(fileService portainer.FileService, signatureService portainer.DigitalSignatureService) error {
+	existingKeyPair, err := fileService.KeyPairFilesExist()
+	if err != nil {
+		log.Fatal().Err(err).Msg("failed checking for existing key pair")
+	}
+
+	if existingKeyPair {
+		return loadAndParseKeyPair(fileService, signatureService)
+	}
+
+	return generateAndStoreKeyPair(fileService, signatureService)
+}
+
+// dbSecretPath build the path to the file that contains the db encryption
+// secret. Normally in Docker this is built from the static path inside
+// /run/secrets for example: /run/secrets/<keyFilenameFlag> but for ease of
+// use outside Docker it also accepts an absolute path
+func dbSecretPath(keyFilenameFlag string) string {
+	if path.IsAbs(keyFilenameFlag) {
+		return keyFilenameFlag
+	}
+	return path.Join("/run/secrets", keyFilenameFlag)
+}
+
+func loadEncryptionSecretKey(keyfilename string) []byte {
+	content, err := os.ReadFile(keyfilename)
+	if err != nil {
+		if os.IsNotExist(err) {
+			log.Info().Str("filename", keyfilename).Msg("encryption key file not present")
+		} else {
+			log.Info().Err(err).Msg("error reading encryption key file")
+		}
+
+		return nil
+	}
+
+	// return a 32 byte hash of the secret (required for AES)
+	// fips compliant version of this is not implemented in -ce
+	hash := sha256.Sum256(content)
+
+	return hash[:]
+}
+
+func buildServer(flags *portainer.CLIFlags, shutdownCtx context.Context, shutdownTrigger context.CancelFunc) portainer.Server {
+	if flags.FeatureFlags != nil {
+		featureflags.Parse(*flags.FeatureFlags, portainer.SupportedFeatureFlags)
+	}
+
+	trustedOrigins := []string{}
+	if *flags.TrustedOrigins != "" {
+		// validate if the trusted origins are valid urls
+		for origin := range strings.SplitSeq(*flags.TrustedOrigins, ",") {
+			if !validate.IsTrustedOrigin(origin) {
+				log.Fatal().Str("trusted_origin", origin).Msg("invalid trusted origin: must be scheme://host or scheme://host:port (e.g. https://example.com)")
+			}
+
+			trustedOrigins = append(trustedOrigins, origin)
+		}
+	}
+
+	// -ce can not ever be run in FIPS mode
+	fips.InitFIPS(false)
+
+	fileService := initFileService(*flags.Data)
+	encryptionKey := loadEncryptionSecretKey(dbSecretPath(*flags.SecretKeyName))
+	if encryptionKey == nil {
+		log.Info().Msg("proceeding without encryption key")
+	}
+
+	dataStore := initDataStore(flags, encryptionKey, fileService, shutdownCtx)
+
+	if err := dataStore.CheckCurrentEdition(); err != nil {
+		log.Fatal().Err(err).Msg("")
+	}
+
+	// check if the db schema version matches with server version
+	if !checkDBSchemaServerVersionMatch(dataStore, portainer.APIVersion, int(portainer.Edition)) {
+		log.Fatal().Msg("The database schema version does not align with the server version. Please consider reverting to the previous server version or addressing the database migration issue.")
+	}
+
+	if err := ssrf.Configure(dataStore.AllowList()); err != nil {
+		log.Fatal().Err(err).Msg("failed initializing ssrf service")
+	}
+
+	if !ssrf.WrapDefaultTransport() {
+		log.Fatal().Msg("failed to wrap default HTTP transport with SSRF protection")
+	}
+
+	gogithttp.DefaultClient = gogithttp.NewClient(&nethttp.Client{Transport: nethttp.DefaultTransport})
+	gogitclient.InstallProtocol("git", git.NewSSRFGitTransport(gogitraw.DefaultClient))
+	gogitclient.InstallProtocol("ssh", git.NewSSRFGitTransport(gogitssh.DefaultClient))
+	gogitclient.InstallProtocol("file", nil)
+
+	instanceID, err := dataStore.Version().InstanceID()
+	if err != nil {
+		log.Fatal().Err(err).Msg("failed getting instance id")
+	}
+
+	apiKeyService := initAPIKeyService(dataStore)
+
+	settings, err := dataStore.Settings().Settings()
+	if err != nil {
+		log.Fatal().Err(err).Msg("")
+	}
+
+	jwtService, err := initJWTService(settings.UserSessionTimeout, dataStore)
+	if err != nil {
+		log.Fatal().Err(err).Msg("failed initializing JWT service")
+	}
+
+	ldapService := ldap.Service{}
+
+	oauthService := oauth.NewService()
+
+	gitService := git.NewService(shutdownCtx)
+
+	cryptoService := crypto.Service{}
+
+	signatureService := initDigitalSignatureService()
+
+	edgeStacksService := edgestacks.NewService(dataStore)
+
+	sslService, err := initSSLService(*flags.AddrHTTPS, *flags.TLSCert, *flags.TLSKey, fileService, dataStore, shutdownTrigger)
+	if err != nil {
+		log.Fatal().Err(err).Msg("")
+	}
+
+	sslSettings, err := sslService.GetSSLSettings()
+	if err != nil {
+		log.Fatal().Err(err).Msg("failed to get SSL settings")
+	}
+
+	if err := initKeyPair(fileService, signatureService); err != nil {
+		log.Fatal().Err(err).Msg("failed initializing key pair")
+	}
+
+	reverseTunnelService := chisel.NewService(dataStore, shutdownCtx, fileService)
+
+	dockerClientFactory := dockerclient.NewClientFactory(signatureService, reverseTunnelService)
+
+	kubernetesClientFactory, err := kubecli.NewClientFactory(signatureService, reverseTunnelService, dataStore, instanceID, *flags.AddrHTTPS, settings.UserSessionTimeout)
+	if err != nil {
+		log.Fatal().Err(err).Msg("failed initializing Kubernetes Client Factory service")
+	}
+
+	authorizationService := authorization.NewService(dataStore)
+	authorizationService.K8sClientFactory = kubernetesClientFactory
+
+	kubernetesTokenCacheManager := kubeproxy.NewTokenCacheManager()
+
+	kubeClusterAccessService := kubernetes.NewKubeClusterAccessService(*flags.BaseURL, *flags.AddrHTTPS, sslSettings.CertPath)
+
+	proxyManager := proxy.NewManager(kubernetesClientFactory)
+
+	reverseTunnelService.ProxyManager = proxyManager
+
+	composeDeployer := compose.NewComposeDeployer()
+
+	composeStackManager := exec.NewComposeStackManager(composeDeployer, proxyManager)
+
+	swarmStackManager := exec.NewSwarmStackManager(libswarm.NewSwarmDeployer(), proxyManager)
+
+	kubernetesDeployer := initKubernetesDeployer(kubernetesTokenCacheManager, kubernetesClientFactory, dataStore, reverseTunnelService, signatureService, proxyManager)
+
+	pendingActionsService := pendingactions.NewService(dataStore, kubernetesClientFactory)
+	pendingActionsService.RegisterHandler(actions.CleanNAPWithOverridePolicies, handlers.NewHandlerCleanNAPWithOverridePolicies(authorizationService, dataStore))
+	pendingActionsService.RegisterHandler(actions.DeletePortainerK8sRegistrySecrets, handlers.NewHandlerDeleteRegistrySecrets(authorizationService, dataStore, kubernetesClientFactory))
+	pendingActionsService.RegisterHandler(actions.PostInitMigrateEnvironment, handlers.NewHandlerPostInitMigrateEnvironment(authorizationService, dataStore, kubernetesClientFactory, dockerClientFactory, *flags.Assets, kubernetesDeployer))
+
+	snapshotService, err := initSnapshotService(*flags.SnapshotInterval, dataStore, dockerClientFactory, kubernetesClientFactory, pendingActionsService)
+	if err != nil {
+		log.Fatal().Err(err).Msg("failed initializing snapshot service")
+	}
+
+	snapshotService.Start(shutdownCtx)
+
+	proxyManager.NewProxyFactory(dataStore, signatureService, reverseTunnelService, dockerClientFactory, kubernetesClientFactory, kubernetesTokenCacheManager, gitService, snapshotService, jwtService)
+
+	helmPackageManager := libhelm.NewHelmPackageManager()
+
+	applicationStatus := initStatus(instanceID)
+
+	// channel to control when the admin user is created
+	adminCreationDone := make(chan struct{}, 1)
+
+	go endpointutils.InitEndpoint(shutdownCtx, adminCreationDone, flags, dataStore, snapshotService)
+
+	adminPasswordHash := ""
+
+	if *flags.AdminPasswordFile != "" {
+		content, err := fileService.GetFileContent(*flags.AdminPasswordFile, "")
+		if err != nil {
+			log.Fatal().Err(err).Msg("failed getting admin password file")
+		}
+
+		adminPasswordHash, err = cryptoService.Hash(strings.TrimSuffix(string(content), "\n"))
+		if err != nil {
+			log.Fatal().Err(err).Msg("failed hashing admin password")
+		}
+	} else if *flags.AdminPassword != "" {
+		adminPasswordHash = *flags.AdminPassword
+	}
+
+	if adminPasswordHash != "" {
+		users, err := dataStore.User().UsersByRole(portainer.AdministratorRole)
+		if err != nil {
+			log.Fatal().Err(err).Msg("failed getting admin user")
+		}
+
+		if len(users) == 0 {
+			log.Info().Msg("created admin user with the given password.")
+
+			user := &portainer.User{
+				Username: "admin",
+				Role:     portainer.AdministratorRole,
+				Password: adminPasswordHash,
+			}
+
+			if err := dataStore.User().Create(user); err != nil {
+				log.Fatal().Err(err).Msg("failed creating admin user")
+			}
+
+			// notify the admin user is created, the endpoint initialization can start
+			adminCreationDone <- struct{}{}
+		} else {
+			log.Info().Msg("instance already has an administrator user defined, skipping admin password related flags.")
+		}
+	}
+
+	setupToken := ""
+	if adminPasswordHash == "" && !*flags.NoSetupToken {
+		if err := dataStore.ViewTx(func(tx dataservices.DataStoreTx) error {
+			var txErr error
+			setupToken, txErr = resolveSetupToken(tx, *flags.SetupToken)
+			return txErr
+		}); err != nil {
+			log.Fatal().Err(err).Msg("failed initializing setup token")
+		}
+	}
+
+	if err := reverseTunnelService.StartTunnelServer(*flags.TunnelAddr, *flags.TunnelPort, snapshotService); err != nil {
+		log.Fatal().Err(err).Msg("failed starting tunnel server")
+	}
+
+	scheduler := scheduler.NewScheduler(shutdownCtx)
+	stackDeployer := deployments.NewStackDeployer(swarmStackManager, composeStackManager, kubernetesDeployer, dockerClientFactory, dataStore)
+	if err := deployments.StartStackSchedules(scheduler, stackDeployer, dataStore, gitService); err != nil {
+		log.Fatal().Err(err).Msg("failed to start stack scheduler")
+	}
+
+	sslDBSettings, err := dataStore.SSLSettings().Settings()
+	if err != nil {
+		log.Fatal().Msg("failed to fetch SSL settings from DB")
+	}
+
+	platformService := platform.NewService(dataStore)
+
+	upgradeService, err := upgrade.NewService(
+		*flags.Assets,
+		kubernetesClientFactory,
+		dockerClientFactory,
+		composeStackManager,
+		dataStore,
+		fileService,
+		stackDeployer,
+	)
+	if err != nil {
+		log.Fatal().Err(err).Msg("failed initializing upgrade service")
+	}
+
+	// Our normal migrations run as part of the database initialization
+	// but some more complex migrations require access to a kubernetes or docker
+	// client. Therefore we run a separate migration process just before
+	// starting the server.
+	postInitMigrator := postinit.NewPostInitMigrator(
+		kubernetesClientFactory,
+		dockerClientFactory,
+		dataStore,
+		*flags.Assets,
+		kubernetesDeployer,
+	)
+	if err := postInitMigrator.PostInitMigrate(); err != nil {
+		log.Fatal().Err(err).Msg("failure during post init migrations")
+	}
+
+	if err := dataStore.UpdateTx(func(tx dataservices.DataStoreTx) error {
+		return recoverStaleDeployingStacks(tx)
+	}); err != nil {
+		log.Info().Err(err).
+			Msg("Error recovering stale deploying stacks")
+	}
+
+	return &http.Server{
+		AuthorizationService:        authorizationService,
+		ReverseTunnelService:        reverseTunnelService,
+		Status:                      applicationStatus,
+		BindAddress:                 *flags.Addr,
+		BindAddressHTTPS:            *flags.AddrHTTPS,
+		CSP:                         *flags.CSP,
+		HTTPEnabled:                 sslDBSettings.HTTPEnabled,
+		AssetsPath:                  *flags.Assets,
+		DataStore:                   dataStore,
+		EdgeStacksService:           edgeStacksService,
+		SwarmStackManager:           swarmStackManager,
+		ComposeStackManager:         composeStackManager,
+		KubernetesDeployer:          kubernetesDeployer,
+		HelmPackageManager:          helmPackageManager,
+		APIKeyService:               apiKeyService,
+		CryptoService:               cryptoService,
+		JWTService:                  jwtService,
+		FileService:                 fileService,
+		LDAPService:                 ldapService,
+		OAuthService:                oauthService,
+		GitService:                  gitService,
+		ProxyManager:                proxyManager,
+		KubernetesTokenCacheManager: kubernetesTokenCacheManager,
+		KubeClusterAccessService:    kubeClusterAccessService,
+		SignatureService:            signatureService,
+		SnapshotService:             snapshotService,
+		SSLService:                  sslService,
+		DockerClientFactory:         dockerClientFactory,
+		KubernetesClientFactory:     kubernetesClientFactory,
+		Scheduler:                   scheduler,
+		ShutdownTrigger:             shutdownTrigger,
+		StackDeployer:               stackDeployer,
+		UpgradeService:              upgradeService,
+		AdminCreationDone:           adminCreationDone,
+		PendingActionsService:       pendingActionsService,
+		PlatformService:             platformService,
+		PullLimitCheckDisabled:      *flags.PullLimitCheckDisabled,
+		TrustedOrigins:              trustedOrigins,
+		SetupToken:                  setupToken,
+	}
+}
+
+func main() {
+	logs.ConfigureLogger()
+	logs.SetLoggingMode("PRETTY")
+
+	flags := initCLI()
+
+	logs.SetLoggingLevel(*flags.LogLevel)
+	logs.SetLoggingMode(*flags.LogMode)
+
+	for {
+		shutdownCtx, shutdownTrigger := context.WithCancel(context.Background())
+		server := buildServer(flags, shutdownCtx, shutdownTrigger)
+
+		log.Info().
+			Str("version", portainer.APIVersion).
+			Str("build_number", build.BuildNumber).
+			Str("image_tag", build.ImageTag).
+			Str("nodejs_version", build.NodejsVersion).
+			Str("pnpm_version", build.PnpmVersion).
+			Str("webpack_version", build.WebpackVersion).
+			Str("go_version", build.GoVersion).
+			Msg("starting Portainer")
+
+		err := server.Start(shutdownCtx)
+
+		log.Info().Err(err).Msg("HTTP server exited")
+	}
+}
+
+// recoverStaleDeployingStacks resets any stack that was left in the Deploying state
+// (e.g. because the server was restarted mid-deployment) to the Error state so the
+// user can retry.
+func recoverStaleDeployingStacks(tx dataservices.DataStoreTx) error {
+	stacks, err := tx.Stack().ReadAll(func(s portainer.Stack) bool {
+		return s.Status == portainer.StackStatusDeploying
+	})
+	if err != nil {
+		return err
+	}
+
+	for _, stack := range stacks {
+		stack.Status = portainer.StackStatusError
+		stack.DeploymentStatus = append(stack.DeploymentStatus, portainer.StackDeploymentStatus{
+			Status:  portainer.StackStatusError,
+			Time:    time.Now().Unix(),
+			Message: "Deployment interrupted by server restart",
+		})
+
+		if err := tx.Stack().Update(stack.ID, &stack); err != nil {
+			log.Warn().Err(err).
+				Int("stack_id", int(stack.ID)).
+				Str("context", "RecoverStaleDeployingStacks").
+				Msg("Unable to recover stale deploying stack")
+			continue
+		}
+		log.Debug().
+			Int("stack_id", int(stack.ID)).
+			Str("stack_name", stack.Name).
+			Str("context", "RecoverStaleDeployingStacks").
+			Msg("Recovered stale deploying stack to error state")
+	}
+
+	return nil
+}

api/cmd/portainer/main_test.go

@@ -0,0 +1,159 @@
+package main
+
+import (
+	"os"
+	"testing"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/filesystem"
+	"github.com/portainer/portainer/api/internal/testhelpers"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_resolveSetupToken(t *testing.T) {
+	t.Parallel()
+
+	t.Run("admin already exists — returns empty token", func(t *testing.T) {
+		admin := portainer.User{Role: portainer.AdministratorRole}
+		store := testhelpers.NewDatastore(testhelpers.WithUsers([]portainer.User{admin}))
+		token, err := resolveSetupToken(store, "")
+		require.NoError(t, err)
+		assert.Empty(t, token)
+	})
+
+	t.Run("no admin — generates a 64-char hex token", func(t *testing.T) {
+		store := testhelpers.NewDatastore(testhelpers.WithUsers([]portainer.User{}))
+		token, err := resolveSetupToken(store, "")
+		require.NoError(t, err)
+		assert.Len(t, token, 64)
+
+		token2, err := resolveSetupToken(store, "")
+		require.NoError(t, err)
+		assert.NotEqual(t, token, token2)
+	})
+
+	t.Run("no admin — uses provided token", func(t *testing.T) {
+		store := testhelpers.NewDatastore(testhelpers.WithUsers([]portainer.User{}))
+		token, err := resolveSetupToken(store, "mysecrettoken")
+		require.NoError(t, err)
+		assert.Equal(t, "mysecrettoken", token)
+	})
+
+	t.Run("admin already exists — ignores provided token", func(t *testing.T) {
+		admin := portainer.User{Role: portainer.AdministratorRole}
+		store := testhelpers.NewDatastore(testhelpers.WithUsers([]portainer.User{admin}))
+		token, err := resolveSetupToken(store, "mysecrettoken")
+		require.NoError(t, err)
+		assert.Empty(t, token)
+	})
+}
+
+const secretFileName = "secret.txt"
+
+func createPasswordFile(t *testing.T, secretPath, password string) string {
+	err := os.WriteFile(secretPath, []byte(password), 0o600)
+	require.NoError(t, err)
+	return secretPath
+}
+
+func TestLoadEncryptionSecretKey(t *testing.T) {
+	t.Parallel()
+	tempDir := t.TempDir()
+	secretPath := filesystem.JoinPaths(tempDir, secretFileName)
+
+	// first pointing to file that does not exist, gives nil hash (no encryption)
+	encryptionKey := loadEncryptionSecretKey(secretPath)
+	require.Nil(t, encryptionKey)
+
+	// point to a directory instead of a file
+	encryptionKey = loadEncryptionSecretKey(tempDir)
+	require.Nil(t, encryptionKey)
+
+	password := "portainer@1234"
+	createPasswordFile(t, secretPath, password)
+
+	encryptionKey = loadEncryptionSecretKey(secretPath)
+	require.NotNil(t, encryptionKey)
+	// should be 32 bytes for aes256 encryption
+	require.Len(t, encryptionKey, 32)
+}
+
+func TestUpdateSettingsFromFlags_KubectlShellImage(t *testing.T) {
+	const existingImage = "existing-image:v1"
+	const newImage = "new-image:v2"
+
+	emptyString := ""
+	falseBool := false
+	var emptyLabels []portainer.Pair
+
+	tests := []struct {
+		name                      string
+		imageSet                  bool
+		flagImage                 string
+		expectedKubectlShellImage string
+	}{
+		{
+			name:                      "flag not set — DB image unchanged",
+			imageSet:                  false,
+			flagImage:                 portainer.DefaultKubectlShellImage,
+			expectedKubectlShellImage: existingImage,
+		},
+		{
+			name:                      "flag set — DB image updated",
+			imageSet:                  true,
+			flagImage:                 newImage,
+			expectedKubectlShellImage: newImage,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			store := testhelpers.NewDatastore(
+				testhelpers.WithSettingsService(&portainer.Settings{
+					KubectlShellImage: existingImage,
+				}),
+				testhelpers.WithSSLSettingsService(&portainer.SSLSettings{}),
+			)
+
+			flags := &portainer.CLIFlags{
+				SnapshotInterval:          &emptyString,
+				Logo:                      &emptyString,
+				EnableEdgeComputeFeatures: &falseBool,
+				Templates:                 &emptyString,
+				Labels:                    &emptyLabels,
+				HTTPDisabled:              &falseBool,
+				HTTPEnabled:               &falseBool,
+			}
+			flags.KubectlShellImage = &tc.flagImage
+			flags.KubectlShellImageSet = tc.imageSet
+
+			err := updateSettingsFromFlags(store, flags)
+			require.NoError(t, err)
+
+			settings, err := store.Settings().Settings()
+			require.NoError(t, err)
+			require.Equal(t, tc.expectedKubectlShellImage, settings.KubectlShellImage)
+		})
+	}
+}
+
+func TestDBSecretPath(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		keyFilenameFlag string
+		expected        string
+	}{
+		{keyFilenameFlag: "secret.txt", expected: "/run/secrets/secret.txt"},
+		{keyFilenameFlag: "/tmp/secret.txt", expected: "/tmp/secret.txt"},
+		{keyFilenameFlag: "/run/secrets/secret.txt", expected: "/run/secrets/secret.txt"},
+		{keyFilenameFlag: "./secret.txt", expected: "/run/secrets/secret.txt"},
+		{keyFilenameFlag: "../secret.txt", expected: "/run/secret.txt"},
+		{keyFilenameFlag: "foo/bar/secret.txt", expected: "/run/secrets/foo/bar/secret.txt"},
+	}
+
+	for _, test := range tests {
+		assert.Equal(t, test.expected, dbSecretPath(test.keyFilenameFlag))
+	}
+}

api/concurrent/concurrent.go

@@ -0,0 +1,148 @@
+// Package concurrent provides utilities for running multiple functions concurrently in Go.
+// For example, many kubernetes calls can take a while to fulfill.  Oftentimes in Portainer
+// we need to get a list of objects from multiple kubernetes REST APIs. We can often call these
+// apis concurrently to speed up the response time.
+// This package provides a clean way to do just that.
+//
+// Examples:
+//   The ConfigMaps and Secrets function converted using concurrent.Run.
+/*
+
+// GetConfigMapsAndSecrets gets all the ConfigMaps AND all the Secrets for a
+// given namespace in a k8s endpoint. The result is a list of both config maps
+// and secrets. The IsSecret boolean property indicates if a given struct is a
+// secret or configmap.
+func (kcl *KubeClient) GetConfigMapsAndSecrets(namespace string) ([]models.K8sConfigMapOrSecret, error) {
+
+	// use closures to capture the current kube client and namespace by declaring wrapper functions
+	// that match the interface signature for concurrent.Func
+
+	listConfigMaps := func(ctx context.Context) (any, error) {
+		return kcl.cli.CoreV1().ConfigMaps(namespace).List(context.Background(), meta.ListOptions{})
+	}
+
+	listSecrets := func(ctx context.Context) (any, error) {
+		return kcl.cli.CoreV1().Secrets(namespace).List(context.Background(), meta.ListOptions{})
+	}
+
+	// run the functions concurrently and wait for results.  We can also pass in a context to cancel.
+	// e.g. Deadline timer.
+	results, err := concurrent.Run(context.TODO(), listConfigMaps, listSecrets)
+	if err != nil {
+		return nil, err
+	}
+
+	var configMapList *core.ConfigMapList
+	var secretList *core.SecretList
+	for _, r := range results {
+		switch v := r.Result.(type) {
+		case *core.ConfigMapList:
+			configMapList = v
+		case *core.SecretList:
+			secretList = v
+		}
+	}
+
+	// TODO: Applications
+	var combined []models.K8sConfigMapOrSecret
+	for _, m := range configMapList.Items {
+		var cm models.K8sConfigMapOrSecret
+		cm.UID = string(m.UID)
+		cm.Name = m.Name
+		cm.Namespace = m.Namespace
+		cm.Annotations = m.Annotations
+		cm.Data = m.Data
+		cm.CreationDate = m.CreationTimestamp.Time.UTC().Format(time.RFC3339)
+		combined = append(combined, cm)
+	}
+
+	for _, s := range secretList.Items {
+		var secret models.K8sConfigMapOrSecret
+		secret.UID = string(s.UID)
+		secret.Name = s.Name
+		secret.Namespace = s.Namespace
+		secret.Annotations = s.Annotations
+		secret.Data = msbToMss(s.Data)
+		secret.CreationDate = s.CreationTimestamp.Time.UTC().Format(time.RFC3339)
+		secret.IsSecret = true
+		secret.SecretType = string(s.Type)
+		combined = append(combined, secret)
+	}
+
+	return combined, nil
+}
+
+*/
+
+package concurrent
+
+import (
+	"context"
+	"sync"
+)
+
+// Result contains the result and any error returned from running a client task function
+type Result struct {
+	Result any   // the result of running the task function
+	Err    error // any error that occurred while running the task function
+}
+
+// Func is a function returns a result or error
+type Func func(ctx context.Context) (any, error)
+
+// Run runs a list of functions returns the results
+func Run(ctx context.Context, maxConcurrency int, tasks ...Func) ([]Result, error) {
+	var wg sync.WaitGroup
+
+	resultsChan := make(chan Result, len(tasks))
+	taskChan := make(chan Func, len(tasks))
+
+	localCtx, cancelCtx := context.WithCancel(ctx)
+	defer cancelCtx()
+
+	runTask := func() {
+		defer wg.Done()
+
+		for fn := range taskChan {
+			result, err := fn(localCtx)
+			resultsChan <- Result{Result: result, Err: err}
+		}
+	}
+
+	// Set maxConcurrency to the number of tasks if zero or negative
+	if maxConcurrency <= 0 {
+		maxConcurrency = len(tasks)
+	}
+
+	// Start worker goroutines
+	for range maxConcurrency {
+		wg.Add(1)
+		go runTask()
+	}
+
+	// Add tasks to the task channel
+	for _, fn := range tasks {
+		taskChan <- fn
+	}
+
+	// Close the task channel to signal workers to stop when all tasks are done
+	close(taskChan)
+
+	// Wait for all workers to complete
+	wg.Wait()
+	close(resultsChan)
+
+	// Collect the results and cancel on error
+	results := make([]Result, 0, len(tasks))
+	for r := range resultsChan {
+		if r.Err != nil {
+			cancelCtx()
+
+			return nil, r.Err
+		}
+
+		results = append(results, r)
+	}
+
+	return results, nil
+}

api/concurrent/concurrent_test.go

@@ -0,0 +1,149 @@
+package concurrent
+
+import (
+	"context"
+	"errors"
+	"sync/atomic"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestRun_AllSucceed(t *testing.T) {
+	t.Parallel()
+
+	fn1 := func(ctx context.Context) (any, error) { return "one", nil }
+	fn2 := func(ctx context.Context) (any, error) { return "two", nil }
+	fn3 := func(ctx context.Context) (any, error) { return "three", nil }
+
+	results, err := Run(t.Context(), 0, fn1, fn2, fn3)
+
+	require.NoError(t, err)
+	require.Len(t, results, 3)
+
+	values := make([]string, 0, len(results))
+	for _, r := range results {
+		values = append(values, r.Result.(string))
+	}
+	require.ElementsMatch(t, []string{"one", "two", "three"}, values)
+}
+
+func TestRun_OneError(t *testing.T) {
+	t.Parallel()
+
+	sentinel := errors.New("task failed")
+
+	fn1 := func(ctx context.Context) (any, error) { return "ok", nil }
+	fn2 := func(ctx context.Context) (any, error) { return nil, sentinel }
+
+	_, err := Run(t.Context(), 0, fn1, fn2)
+
+	require.ErrorIs(t, err, sentinel)
+}
+
+func TestRun_NoTasks(t *testing.T) {
+	t.Parallel()
+
+	results, err := Run(t.Context(), 0)
+
+	require.NoError(t, err)
+	require.Empty(t, results)
+}
+
+func TestRun_MaxConcurrency(t *testing.T) {
+	t.Parallel()
+
+	const numTasks = 10
+	var peak atomic.Int32
+	var active atomic.Int32
+
+	task := func(ctx context.Context) (any, error) {
+		current := active.Add(1)
+		if current > peak.Load() {
+			peak.Store(current)
+		}
+
+		time.Sleep(10 * time.Millisecond)
+		active.Add(-1)
+
+		return nil, nil
+	}
+
+	tasks := make([]Func, numTasks)
+	for i := range tasks {
+		tasks[i] = task
+	}
+
+	synctest.Test(t, func(t *testing.T) {
+		results, err := Run(t.Context(), 3, tasks...)
+		require.NoError(t, err)
+		require.Len(t, results, numTasks)
+		require.LessOrEqual(t, peak.Load(), int32(3))
+	})
+}
+
+func TestRun_ZeroConcurrencyUsesAllTasks(t *testing.T) {
+	t.Parallel()
+
+	const numTasks = 5
+	var peak atomic.Int32
+	var active atomic.Int32
+
+	task := func(ctx context.Context) (any, error) {
+		current := active.Add(1)
+		if current > peak.Load() {
+			peak.Store(current)
+		}
+
+		time.Sleep(20 * time.Millisecond)
+		active.Add(-1)
+
+		return nil, nil
+	}
+
+	tasks := make([]Func, numTasks)
+	for i := range tasks {
+		tasks[i] = task
+	}
+
+	synctest.Test(t, func(t *testing.T) {
+		results, err := Run(t.Context(), 0, tasks...)
+		require.NoError(t, err)
+		require.Len(t, results, numTasks)
+		require.Equal(t, int32(numTasks), peak.Load())
+	})
+}
+
+func TestRun_ContextCancelledBeforeStart(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithCancel(t.Context())
+	cancel()
+
+	called := atomic.Bool{}
+	fn := func(ctx context.Context) (any, error) {
+		called.Store(true)
+		return nil, ctx.Err()
+	}
+
+	_, err := Run(ctx, 1, fn, fn, fn)
+	require.Error(t, err)
+}
+
+func TestRun_ContextPassedToTasks(t *testing.T) {
+	t.Parallel()
+
+	type key struct{}
+	ctx := context.WithValue(t.Context(), key{}, "testvalue")
+
+	fn := func(ctx context.Context) (any, error) {
+		return ctx.Value(key{}), nil
+	}
+
+	results, err := Run(ctx, 0, fn)
+
+	require.NoError(t, err)
+	require.Equal(t, "testvalue", results[0].Result)
+}

api/connection.go

@@ -0,0 +1,56 @@
+package portainer
+
+import (
+	"io"
+)
+
+type ReadTransaction interface {
+	GetObject(bucketName string, key []byte, object any) error
+	GetRawBytes(bucketName string, key []byte) ([]byte, error)
+	GetAll(bucketName string, obj any, append func(o any) (any, error)) error
+	GetAllWithKeyPrefix(bucketName string, keyPrefix []byte, obj any, append func(o any) (any, error)) error
+	KeyExists(bucketName string, key []byte) (bool, error)
+}
+
+type Transaction interface {
+	ReadTransaction
+
+	SetServiceName(bucketName string) error
+	UpdateObject(bucketName string, key []byte, object any) error
+	DeleteObject(bucketName string, key []byte) error
+	CreateObject(bucketName string, fn func(uint64) (int, any)) error
+	CreateObjectWithId(bucketName string, id int, obj any) error
+	CreateObjectWithStringId(bucketName string, id []byte, obj any) error
+	DeleteAllObjects(bucketName string, obj any, matching func(o any) (id int, ok bool)) error
+	GetNextIdentifier(bucketName string) int
+}
+
+type Connection interface {
+	Transaction
+
+	Open() error
+	Close() error
+
+	UpdateTx(fn func(Transaction) error) error
+	ViewTx(fn func(Transaction) error) error
+
+	// write the db contents to filename as json (the schema needs defining)
+	ExportRaw(filename string) error
+
+	// TODO: this one is very database specific atm
+	BackupTo(w io.Writer) error
+	GetDatabaseFileName() string
+	GetDatabaseFilePath() string
+	GetStorePath() string
+	GetDatabaseFileSize() (int64, error)
+
+	IsEncryptedStore() bool
+	NeedsEncryptionMigration() (bool, error)
+	SetEncrypted(encrypted bool) error
+
+	BackupMetadata() (map[string]any, error)
+	RestoreMetadata(s map[string]any) error
+
+	UpdateObjectFunc(bucketName string, key []byte, object any, updateFn func()) error
+	ConvertToKey(v int) []byte
+}

api/crypto/aes.go

@@ -0,0 +1,410 @@
+package crypto
+
+import (
+	"bufio"
+	"bytes"
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/pbkdf2"
+	"crypto/rand"
+	"crypto/sha256"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/portainer/portainer/pkg/fips"
+
+	// Not allowed in FIPS mode
+	"golang.org/x/crypto/argon2" //nolint:depguard
+	"golang.org/x/crypto/scrypt" //nolint:depguard
+)
+
+const (
+	// AES GCM settings
+	aesGcmHeader    = "AES256-GCM" // The encrypted file header
+	aesGcmBlockSize = 1024 * 1024  // 1MB block for aes gcm
+
+	aesGcmFIPSHeader    = "FIPS-AES256-GCM"
+	aesGcmFIPSBlockSize = 16 * 1024 * 1024 // 16MB block for aes gcm
+
+	// Argon2 settings
+	// Recommended settings lower memory hardware according to current OWASP recommendations
+	// Considering some people run portainer on a NAS I think it's prudent not to assume we're on server grade hardware
+	// https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#argon2id
+	argon2MemoryCost = 12 * 1024
+	argon2TimeCost   = 3
+	argon2Threads    = 1
+	argon2KeyLength  = 32
+
+	pbkdf2Iterations = 600_000 // use recommended iterations from https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#pbkdf2 a little overkill for this use
+	pbkdf2SaltLength = 32
+)
+
+// AesEncrypt reads from input, encrypts with AES-256 and writes to output. passphrase is used to generate an encryption key
+func AesEncrypt(input io.Reader, output io.Writer, passphrase []byte) error {
+	if fips.FIPSMode() {
+		if err := aesEncryptGCMFIPS(input, output, passphrase); err != nil {
+			return fmt.Errorf("error encrypting file: %w", err)
+		}
+	} else {
+		if err := aesEncryptGCM(input, output, passphrase); err != nil {
+			return fmt.Errorf("error encrypting file: %w", err)
+		}
+	}
+
+	return nil
+}
+
+// AesDecrypt reads from input, decrypts with AES-256 and returns the reader to read the decrypted content from
+func AesDecrypt(input io.Reader, passphrase []byte) (io.Reader, error) {
+	return aesDecrypt(input, passphrase, fips.FIPSMode())
+}
+
+func aesDecrypt(input io.Reader, passphrase []byte, fipsMode bool) (io.Reader, error) {
+	// Read file header to determine how it was encrypted
+	inputReader := bufio.NewReader(input)
+	header, err := inputReader.Peek(len(aesGcmFIPSHeader))
+	if err != nil {
+		return nil, fmt.Errorf("error reading encrypted backup file header: %w", err)
+	}
+
+	if strings.HasPrefix(string(header), aesGcmFIPSHeader) {
+		if !fipsMode {
+			return nil, errors.New("fips encrypted file detected but fips mode is not enabled")
+		}
+
+		reader, err := aesDecryptGCMFIPS(inputReader, passphrase)
+		if err != nil {
+			return nil, fmt.Errorf("error decrypting file: %w", err)
+		}
+
+		return reader, nil
+	}
+
+	if strings.HasPrefix(string(header), aesGcmHeader) {
+		if fipsMode {
+			return nil, errors.New("fips mode is enabled but non-fips encrypted file detected")
+		}
+
+		reader, err := aesDecryptGCM(inputReader, passphrase)
+		if err != nil {
+			return nil, fmt.Errorf("error decrypting file: %w", err)
+		}
+
+		return reader, nil
+	}
+
+	// Use the previous decryption routine which has no header (to support older archives)
+	reader, err := aesDecryptOFB(inputReader, passphrase)
+	if err != nil {
+		return nil, fmt.Errorf("error decrypting legacy file backup: %w", err)
+	}
+
+	return reader, nil
+}
+
+// aesEncryptGCM reads from input, encrypts with AES-256 and writes to output. passphrase is used to generate an encryption key.
+func aesEncryptGCM(input io.Reader, output io.Writer, passphrase []byte) error {
+	// Derive key using argon2 with a random salt
+	salt := make([]byte, 16) // 16 bytes salt
+	if _, err := io.ReadFull(rand.Reader, salt); err != nil {
+		return err
+	}
+
+	key := argon2.IDKey(passphrase, salt, argon2TimeCost, argon2MemoryCost, argon2Threads, 32)
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return err
+	}
+
+	aesgcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return err
+	}
+
+	// Generate nonce
+	nonce, err := NewRandomNonce(aesgcm.NonceSize())
+	if err != nil {
+		return err
+	}
+
+	// write the header
+	if _, err := output.Write([]byte(aesGcmHeader)); err != nil {
+		return err
+	}
+
+	// Write nonce and salt to the output file
+	if _, err := output.Write(salt); err != nil {
+		return err
+	}
+	if _, err := output.Write(nonce.Value()); err != nil {
+		return err
+	}
+
+	// Buffer for reading plaintext blocks
+	buf := make([]byte, aesGcmBlockSize) // Adjust buffer size as needed
+	ciphertext := make([]byte, len(buf)+aesgcm.Overhead())
+
+	// Encrypt plaintext in blocks
+	for {
+		n, err := io.ReadFull(input, buf)
+		if n == 0 {
+			break // end of plaintext input
+		}
+
+		if err != nil && !errors.Is(err, io.EOF) && !errors.Is(err, io.ErrUnexpectedEOF) {
+			return err
+		}
+
+		// Seal encrypts the plaintext using the nonce returning the updated slice.
+		ciphertext = aesgcm.Seal(ciphertext[:0], nonce.Value(), buf[:n], nil)
+
+		if _, err := output.Write(ciphertext); err != nil {
+			return err
+		}
+
+		if err := nonce.Increment(); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// aesDecryptGCM reads from input, decrypts with AES-256 and returns the reader to read the decrypted content from.
+func aesDecryptGCM(input io.Reader, passphrase []byte) (io.Reader, error) {
+	// Reader & verify header
+	header := make([]byte, len(aesGcmHeader))
+	if _, err := io.ReadFull(input, header); err != nil {
+		return nil, err
+	}
+
+	if string(header) != aesGcmHeader {
+		return nil, errors.New("invalid header")
+	}
+
+	// Read salt
+	salt := make([]byte, 16) // Salt size
+	if _, err := io.ReadFull(input, salt); err != nil {
+		return nil, err
+	}
+
+	key := argon2.IDKey(passphrase, salt, argon2TimeCost, argon2MemoryCost, argon2Threads, 32)
+
+	// Initialize AES cipher block
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+
+	// Create GCM mode with the cipher block
+	aesgcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, err
+	}
+
+	// Read nonce from the input reader
+	nonce := NewNonce(aesgcm.NonceSize())
+	if err := nonce.Read(input); err != nil {
+		return nil, err
+	}
+
+	// Initialize a buffer to store decrypted data
+	buf := bytes.Buffer{}
+	plaintext := make([]byte, aesGcmBlockSize)
+
+	// Decrypt the ciphertext in blocks
+	for {
+		// Read a block of ciphertext from the input reader
+		ciphertextBlock := make([]byte, aesGcmBlockSize+aesgcm.Overhead()) // Adjust block size as needed
+		n, err := io.ReadFull(input, ciphertextBlock)
+		if n == 0 {
+			break // end of ciphertext
+		}
+
+		if err != nil && !errors.Is(err, io.EOF) && !errors.Is(err, io.ErrUnexpectedEOF) {
+			return nil, err
+		}
+
+		// Decrypt the block of ciphertext
+		plaintext, err = aesgcm.Open(plaintext[:0], nonce.Value(), ciphertextBlock[:n], nil)
+		if err != nil {
+			return nil, err
+		}
+
+		if _, err := buf.Write(plaintext); err != nil {
+			return nil, err
+		}
+
+		if err := nonce.Increment(); err != nil {
+			return nil, err
+		}
+	}
+
+	return &buf, nil
+}
+
+// aesEncryptGCMFIPS reads from input, encrypts with AES-256 in a fips compliant
+// way and writes to output. passphrase is used to generate an encryption key.
+func aesEncryptGCMFIPS(input io.Reader, output io.Writer, passphrase []byte) error {
+	salt := make([]byte, pbkdf2SaltLength)
+	if _, err := io.ReadFull(rand.Reader, salt); err != nil {
+		return err
+	}
+
+	key, err := pbkdf2.Key(sha256.New, string(passphrase), salt, pbkdf2Iterations, 32)
+	if err != nil {
+		return fmt.Errorf("error deriving key: %w", err)
+	}
+
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return err
+	}
+
+	// write the header
+	if _, err := output.Write([]byte(aesGcmFIPSHeader)); err != nil {
+		return err
+	}
+
+	// Write nonce and salt to the output file
+	if _, err := output.Write(salt); err != nil {
+		return err
+	}
+
+	// Buffer for reading plaintext blocks
+	buf := make([]byte, aesGcmFIPSBlockSize)
+
+	// Encrypt plaintext in blocks
+	for {
+		// new random nonce for each block
+		aesgcm, err := cipher.NewGCMWithRandomNonce(block)
+		if err != nil {
+			return fmt.Errorf("error creating gcm: %w", err)
+		}
+
+		n, err := io.ReadFull(input, buf)
+		if n == 0 {
+			break // end of plaintext input
+		}
+
+		if err != nil && !errors.Is(err, io.EOF) && !errors.Is(err, io.ErrUnexpectedEOF) {
+			return err
+		}
+
+		// Seal encrypts the plaintext
+		ciphertext := aesgcm.Seal(nil, nil, buf[:n], nil)
+
+		if _, err := output.Write(ciphertext); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// aesDecryptGCMFIPS reads from input, decrypts with AES-256 in a fips compliant
+// way and returns the reader to read the decrypted content from.
+func aesDecryptGCMFIPS(input io.Reader, passphrase []byte) (io.Reader, error) {
+	// Reader & verify header
+	header := make([]byte, len(aesGcmFIPSHeader))
+	if _, err := io.ReadFull(input, header); err != nil {
+		return nil, err
+	}
+
+	if string(header) != aesGcmFIPSHeader {
+		return nil, errors.New("invalid header")
+	}
+
+	// Read salt
+	salt := make([]byte, pbkdf2SaltLength)
+	if _, err := io.ReadFull(input, salt); err != nil {
+		return nil, err
+	}
+
+	key, err := pbkdf2.Key(sha256.New, string(passphrase), salt, pbkdf2Iterations, 32)
+	if err != nil {
+		return nil, fmt.Errorf("error deriving key: %w", err)
+	}
+
+	// Initialize AES cipher block
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+
+	// Initialize a buffer to store decrypted data
+	buf := bytes.Buffer{}
+
+	// Decrypt the ciphertext in blocks
+	for {
+		// Create GCM mode with the cipher block
+		aesgcm, err := cipher.NewGCMWithRandomNonce(block)
+		if err != nil {
+			return nil, err
+		}
+
+		// Read a block of ciphertext from the input reader
+		ciphertextBlock := make([]byte, aesGcmFIPSBlockSize+aesgcm.Overhead())
+		n, err := io.ReadFull(input, ciphertextBlock)
+		if n == 0 {
+			break // end of ciphertext
+		}
+
+		if err != nil && !errors.Is(err, io.EOF) && !errors.Is(err, io.ErrUnexpectedEOF) {
+			return nil, err
+		}
+
+		// Decrypt the block of ciphertext
+		plaintext, err := aesgcm.Open(nil, nil, ciphertextBlock[:n], nil)
+		if err != nil {
+			return nil, err
+		}
+
+		if _, err := buf.Write(plaintext); err != nil {
+			return nil, err
+		}
+	}
+
+	return &buf, nil
+}
+
+// aesDecryptOFB reads from input, decrypts with AES-256 and returns the reader to a read decrypted content from.
+// passphrase is used to generate an encryption key.
+// note: This function used to decrypt files that were encrypted without a header i.e. old archives
+func aesDecryptOFB(input io.Reader, passphrase []byte) (io.Reader, error) {
+	// making a 32 bytes key that would correspond to AES-256
+	// don't necessarily need a salt, so just kept in empty
+	key, err := scrypt.Key(passphrase, nil, 32768, 8, 1, 32)
+	if err != nil {
+		return nil, err
+	}
+
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+
+	// If the key is unique for each ciphertext, then it's ok to use a zero IV.
+	var iv [aes.BlockSize]byte
+	stream := cipher.NewOFB(block, iv[:])
+	reader := &cipher.StreamReader{S: stream, R: input}
+
+	return reader, nil
+}
+
+// HasEncryptedHeader checks if the data has an encrypted header, note that fips
+// mode changes this behavior and so will only recognize data encrypted by the
+// same mode (fips enabled or disabled)
+func HasEncryptedHeader(data []byte) bool {
+	return hasEncryptedHeader(data, fips.FIPSMode())
+}
+
+func hasEncryptedHeader(data []byte, fipsMode bool) bool {
+	if fipsMode {
+		return bytes.HasPrefix(data, []byte(aesGcmFIPSHeader))
+	}
+
+	return bytes.HasPrefix(data, []byte(aesGcmHeader))
+}

api/crypto/aes_test.go

@@ -0,0 +1,449 @@
+package crypto
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"io"
+	"math/rand"
+	"os"
+	"testing"
+
+	"github.com/portainer/portainer/api/filesystem"
+	"github.com/portainer/portainer/api/logs"
+	"github.com/portainer/portainer/pkg/fips"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/crypto/scrypt"
+)
+
+func init() {
+	fips.InitFIPS(false)
+}
+
+const letterBytes = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+func randBytes(n int) []byte {
+	b := make([]byte, n)
+	for i := range b {
+		b[i] = letterBytes[rand.Intn(len(letterBytes))]
+	}
+
+	return b
+}
+
+type encryptFunc func(input io.Reader, output io.Writer, passphrase []byte) error
+type decryptFunc func(input io.Reader, passphrase []byte) (io.Reader, error)
+
+func Test_encryptAndDecrypt_withTheSamePassword(t *testing.T) {
+	const passphrase = "passphrase"
+
+	testFunc := func(t *testing.T, encrypt encryptFunc, decrypt decryptFunc, decryptShouldSucceed bool) {
+		tmpdir := t.TempDir()
+
+		var (
+			originFilePath    = filesystem.JoinPaths(tmpdir, "origin")
+			encryptedFilePath = filesystem.JoinPaths(tmpdir, "encrypted")
+			decryptedFilePath = filesystem.JoinPaths(tmpdir, "decrypted")
+		)
+
+		content := randBytes(1024*1024*100 + 523)
+		err := os.WriteFile(originFilePath, content, 0600)
+		require.NoError(t, err)
+
+		originFile, _ := os.Open(originFilePath)
+		defer logs.CloseAndLogErr(originFile)
+
+		encryptedFileWriter, _ := os.Create(encryptedFilePath)
+
+		err = encrypt(originFile, encryptedFileWriter, []byte(passphrase))
+		require.NoError(t, err, "Failed to encrypt a file")
+		logs.CloseAndLogErr(encryptedFileWriter)
+
+		encryptedContent, err := os.ReadFile(encryptedFilePath)
+		require.NoError(t, err, "Couldn't read encrypted file")
+		assert.NotEqual(t, encryptedContent, content, "Content wasn't encrypted")
+
+		encryptedFileReader, err := os.Open(encryptedFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(encryptedFileReader)
+
+		decryptedFileWriter, err := os.Create(decryptedFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(decryptedFileWriter)
+
+		decryptedReader, err := decrypt(encryptedFileReader, []byte(passphrase))
+		if !decryptShouldSucceed {
+			require.Error(t, err, "Failed to decrypt file as indicated by decryptShouldSucceed")
+		} else {
+			require.NoError(t, err, "Failed to decrypt file indicated by decryptShouldSucceed")
+
+			_, err = io.Copy(decryptedFileWriter, decryptedReader)
+			require.NoError(t, err)
+
+			decryptedContent, err := os.ReadFile(decryptedFilePath)
+			require.NoError(t, err)
+			assert.Equal(t, content, decryptedContent, "Original and decrypted content should match")
+		}
+	}
+
+	t.Run("fips", func(t *testing.T) {
+		testFunc(t, aesEncryptGCMFIPS, aesDecryptGCMFIPS, true)
+	})
+
+	t.Run("non_fips", func(t *testing.T) {
+		testFunc(t, aesEncryptGCM, aesDecryptGCM, true)
+	})
+
+	t.Run("system_fips_mode_public_entry_points", func(t *testing.T) {
+		// use the init mode, public entry points
+		testFunc(t, AesEncrypt, AesDecrypt, true)
+	})
+
+	t.Run("fips_encrypted_file_header_fails_in_non_fips_mode", func(t *testing.T) {
+		// use aesDecrypt which checks the header, confirm that it fails
+		decrypt := func(input io.Reader, passphrase []byte) (io.Reader, error) {
+			return aesDecrypt(input, passphrase, false)
+		}
+
+		testFunc(t, aesEncryptGCMFIPS, decrypt, false)
+	})
+
+	t.Run("non_fips_encrypted_file_header_fails_in_fips_mode", func(t *testing.T) {
+		// use aesDecrypt which checks the header, confirm that it fails
+		decrypt := func(input io.Reader, passphrase []byte) (io.Reader, error) {
+			return aesDecrypt(input, passphrase, true)
+		}
+
+		testFunc(t, aesEncryptGCM, decrypt, false)
+	})
+
+	t.Run("fips_encrypted_file_fails_in_non_fips_mode", func(t *testing.T) {
+		testFunc(t, aesEncryptGCMFIPS, aesDecryptGCM, false)
+	})
+
+	t.Run("non_fips_encrypted_file_with_fips_mode_should_fail", func(t *testing.T) {
+		testFunc(t, aesEncryptGCM, aesDecryptGCMFIPS, false)
+	})
+
+	t.Run("fips_with_base_aesDecrypt", func(t *testing.T) {
+		// maximize coverage, use the base aesDecrypt function with valid fips mode
+		decrypt := func(input io.Reader, passphrase []byte) (io.Reader, error) {
+			return aesDecrypt(input, passphrase, true)
+		}
+
+		testFunc(t, aesEncryptGCMFIPS, decrypt, true)
+	})
+
+	t.Run("legacy", func(t *testing.T) {
+		testFunc(t, legacyAesEncrypt, aesDecryptOFB, true)
+	})
+}
+
+func Test_encryptAndDecrypt_withStrongPassphrase(t *testing.T) {
+	t.Parallel()
+	const passphrase = "A strong passphrase with special characters: !@#$%^&*()_+"
+
+	testFunc := func(t *testing.T, encrypt encryptFunc, decrypt decryptFunc) {
+		tmpdir := t.TempDir()
+
+		var (
+			originFilePath    = filesystem.JoinPaths(tmpdir, "origin2")
+			encryptedFilePath = filesystem.JoinPaths(tmpdir, "encrypted2")
+			decryptedFilePath = filesystem.JoinPaths(tmpdir, "decrypted2")
+		)
+
+		content := randBytes(500)
+
+		err := os.WriteFile(originFilePath, content, 0600)
+		require.NoError(t, err)
+
+		originFile, err := os.Open(originFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(originFile)
+
+		encryptedFileWriter, _ := os.Create(encryptedFilePath)
+
+		err = encrypt(originFile, encryptedFileWriter, []byte(passphrase))
+		require.NoError(t, err, "Failed to encrypt a file")
+		logs.CloseAndLogErr(encryptedFileWriter)
+
+		encryptedContent, err := os.ReadFile(encryptedFilePath)
+		require.NoError(t, err, "Couldn't read encrypted file")
+		assert.NotEqual(t, encryptedContent, content, "Content wasn't encrypted")
+
+		encryptedFileReader, err := os.Open(encryptedFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(encryptedFileReader)
+
+		decryptedFileWriter, err := os.Create(decryptedFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(decryptedFileWriter)
+
+		decryptedReader, err := decrypt(encryptedFileReader, []byte(passphrase))
+		require.NoError(t, err, "Failed to decrypt file")
+
+		_, err = io.Copy(decryptedFileWriter, decryptedReader)
+		require.NoError(t, err)
+
+		decryptedContent, err := os.ReadFile(decryptedFilePath)
+		require.NoError(t, err)
+		assert.Equal(t, content, decryptedContent, "Original and decrypted content should match")
+	}
+
+	t.Run("fips", func(t *testing.T) {
+		testFunc(t, aesEncryptGCMFIPS, aesDecryptGCMFIPS)
+	})
+
+	t.Run("non_fips", func(t *testing.T) {
+		testFunc(t, aesEncryptGCM, aesDecryptGCM)
+	})
+}
+
+func Test_encryptAndDecrypt_withTheSamePasswordSmallFile(t *testing.T) {
+	t.Parallel()
+	testFunc := func(t *testing.T, encrypt encryptFunc, decrypt decryptFunc) {
+		tmpdir := t.TempDir()
+
+		var (
+			originFilePath    = filesystem.JoinPaths(tmpdir, "origin2")
+			encryptedFilePath = filesystem.JoinPaths(tmpdir, "encrypted2")
+			decryptedFilePath = filesystem.JoinPaths(tmpdir, "decrypted2")
+		)
+
+		content := randBytes(500)
+		err := os.WriteFile(originFilePath, content, 0600)
+		require.NoError(t, err)
+
+		originFile, err := os.Open(originFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(originFile)
+
+		encryptedFileWriter, err := os.Create(encryptedFilePath)
+		require.NoError(t, err)
+
+		err = encrypt(originFile, encryptedFileWriter, []byte("passphrase"))
+		require.NoError(t, err, "Failed to encrypt a file")
+		logs.CloseAndLogErr(encryptedFileWriter)
+
+		encryptedContent, err := os.ReadFile(encryptedFilePath)
+		require.NoError(t, err, "Couldn't read encrypted file")
+		assert.NotEqual(t, encryptedContent, content, "Content wasn't encrypted")
+
+		encryptedFileReader, err := os.Open(encryptedFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(encryptedFileReader)
+
+		decryptedFileWriter, err := os.Create(decryptedFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(decryptedFileWriter)
+
+		decryptedReader, err := decrypt(encryptedFileReader, []byte("passphrase"))
+		require.NoError(t, err, "Failed to decrypt file")
+
+		_, err = io.Copy(decryptedFileWriter, decryptedReader)
+		require.NoError(t, err)
+
+		decryptedContent, err := os.ReadFile(decryptedFilePath)
+		require.NoError(t, err)
+		assert.Equal(t, content, decryptedContent, "Original and decrypted content should match")
+	}
+
+	t.Run("fips", func(t *testing.T) {
+		testFunc(t, aesEncryptGCMFIPS, aesDecryptGCMFIPS)
+	})
+
+	t.Run("non_fips", func(t *testing.T) {
+		testFunc(t, aesEncryptGCM, aesDecryptGCM)
+	})
+}
+
+func Test_encryptAndDecrypt_withEmptyPassword(t *testing.T) {
+	t.Parallel()
+	testFunc := func(t *testing.T, encrypt encryptFunc, decrypt decryptFunc) {
+		tmpdir := t.TempDir()
+
+		var (
+			originFilePath    = filesystem.JoinPaths(tmpdir, "origin")
+			encryptedFilePath = filesystem.JoinPaths(tmpdir, "encrypted")
+			decryptedFilePath = filesystem.JoinPaths(tmpdir, "decrypted")
+		)
+
+		content := randBytes(1024 * 50)
+		err := os.WriteFile(originFilePath, content, 0600)
+		require.NoError(t, err)
+
+		originFile, err := os.Open(originFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(originFile)
+
+		encryptedFileWriter, err := os.Create(encryptedFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(encryptedFileWriter)
+
+		err = encrypt(originFile, encryptedFileWriter, []byte(""))
+		require.NoError(t, err, "Failed to encrypt a file")
+
+		encryptedContent, err := os.ReadFile(encryptedFilePath)
+		require.NoError(t, err, "Couldn't read encrypted file")
+		assert.NotEqual(t, encryptedContent, content, "Content wasn't encrypted")
+
+		encryptedFileReader, err := os.Open(encryptedFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(encryptedFileReader)
+
+		decryptedFileWriter, err := os.Create(decryptedFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(decryptedFileWriter)
+
+		decryptedReader, err := decrypt(encryptedFileReader, []byte(""))
+		require.NoError(t, err, "Failed to decrypt file")
+
+		_, err = io.Copy(decryptedFileWriter, decryptedReader)
+		require.NoError(t, err)
+
+		decryptedContent, err := os.ReadFile(decryptedFilePath)
+		require.NoError(t, err)
+		assert.Equal(t, content, decryptedContent, "Original and decrypted content should match")
+	}
+
+	t.Run("fips", func(t *testing.T) {
+		testFunc(t, aesEncryptGCMFIPS, aesDecryptGCMFIPS)
+	})
+
+	t.Run("non_fips", func(t *testing.T) {
+		testFunc(t, aesEncryptGCM, aesDecryptGCM)
+	})
+}
+
+func Test_decryptWithDifferentPassphrase_shouldProduceWrongResult(t *testing.T) {
+	t.Parallel()
+	testFunc := func(t *testing.T, encrypt encryptFunc, decrypt decryptFunc) {
+		tmpdir := t.TempDir()
+
+		var (
+			originFilePath    = filesystem.JoinPaths(tmpdir, "origin")
+			encryptedFilePath = filesystem.JoinPaths(tmpdir, "encrypted")
+			decryptedFilePath = filesystem.JoinPaths(tmpdir, "decrypted")
+		)
+
+		content := randBytes(1034)
+		err := os.WriteFile(originFilePath, content, 0600)
+		require.NoError(t, err)
+
+		originFile, err := os.Open(originFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(originFile)
+
+		encryptedFileWriter, err := os.Create(encryptedFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(encryptedFileWriter)
+
+		err = encrypt(originFile, encryptedFileWriter, []byte("passphrase"))
+		require.NoError(t, err, "Failed to encrypt a file")
+		encryptedContent, err := os.ReadFile(encryptedFilePath)
+		require.NoError(t, err, "Couldn't read encrypted file")
+		assert.NotEqual(t, encryptedContent, content, "Content wasn't encrypted")
+
+		encryptedFileReader, err := os.Open(encryptedFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(encryptedFileReader)
+
+		decryptedFileWriter, err := os.Create(decryptedFilePath)
+		require.NoError(t, err)
+		defer logs.CloseAndLogErr(decryptedFileWriter)
+
+		_, err = decrypt(encryptedFileReader, []byte("garbage"))
+		require.Error(t, err, "Should not allow decrypt with wrong passphrase")
+	}
+
+	t.Run("fips", func(t *testing.T) {
+		testFunc(t, aesEncryptGCMFIPS, aesDecryptGCMFIPS)
+	})
+
+	t.Run("non_fips", func(t *testing.T) {
+		testFunc(t, aesEncryptGCM, aesDecryptGCM)
+	})
+}
+
+func legacyAesEncrypt(input io.Reader, output io.Writer, passphrase []byte) error {
+	key, err := scrypt.Key(passphrase, nil, 32768, 8, 1, 32)
+	if err != nil {
+		return err
+	}
+
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return err
+	}
+
+	var iv [aes.BlockSize]byte
+	stream := cipher.NewOFB(block, iv[:])
+
+	writer := &cipher.StreamWriter{S: stream, W: output}
+	if _, err := io.Copy(writer, input); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func Test_hasEncryptedHeader(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		name     string
+		data     []byte
+		fipsMode bool
+		want     bool
+	}{
+		{
+			name:     "non-FIPS mode with valid header",
+			data:     []byte("AES256-GCM" + "some encrypted data"),
+			fipsMode: false,
+			want:     true,
+		},
+		{
+			name:     "non-FIPS mode with FIPS header",
+			data:     []byte("FIPS-AES256-GCM" + "some encrypted data"),
+			fipsMode: false,
+			want:     false,
+		},
+		{
+			name:     "FIPS mode with valid header",
+			data:     []byte("FIPS-AES256-GCM" + "some encrypted data"),
+			fipsMode: true,
+			want:     true,
+		},
+		{
+			name:     "FIPS mode with non-FIPS header",
+			data:     []byte("AES256-GCM" + "some encrypted data"),
+			fipsMode: true,
+			want:     false,
+		},
+		{
+			name:     "invalid header",
+			data:     []byte("INVALID-HEADER" + "some data"),
+			fipsMode: false,
+			want:     false,
+		},
+		{
+			name:     "empty data",
+			data:     []byte{},
+			fipsMode: false,
+			want:     false,
+		},
+		{
+			name:     "nil data",
+			data:     nil,
+			fipsMode: false,
+			want:     false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := hasEncryptedHeader(tt.data, tt.fipsMode)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}

api/crypto/ecdsa.go

@@ -0,0 +1,135 @@
+package crypto
+
+import (
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/hex"
+
+	"github.com/portainer/portainer/pkg/libcrypto"
+)
+
+const (
+	// PrivateKeyPemHeader represents the header that is appended to the PEM file when
+	// storing the private key.
+	PrivateKeyPemHeader = "EC PRIVATE KEY"
+	// PublicKeyPemHeader represents the header that is appended to the PEM file when
+	// storing the public key.
+	PublicKeyPemHeader = "ECDSA PUBLIC KEY"
+)
+
+// ECDSAService is a service used to create digital signatures when communicating with
+// an agent based environment(endpoint). It will automatically generates a key pair using ECDSA or
+// can also reuse an existing ECDSA key pair.
+type ECDSAService struct {
+	privateKey    *ecdsa.PrivateKey
+	publicKey     *ecdsa.PublicKey
+	encodedPubKey string
+	secret        string
+}
+
+// NewECDSAService returns a pointer to a ECDSAService.
+// An optional secret can be specified
+func NewECDSAService(secret string) *ECDSAService {
+	return &ECDSAService{
+		secret: secret,
+	}
+}
+
+// EncodedPublicKey returns the encoded version of the public that can be used
+// to be shared with other services. It's the hexadecimal encoding of the public key
+// content.
+func (service *ECDSAService) EncodedPublicKey() string {
+	return service.encodedPubKey
+}
+
+// PEMHeaders returns the ECDSA PEM headers.
+func (service *ECDSAService) PEMHeaders() (string, string) {
+	return PrivateKeyPemHeader, PublicKeyPemHeader
+}
+
+// ParseKeyPair parses existing private/public key pair content and associate
+// the parsed keys to the service.
+func (service *ECDSAService) ParseKeyPair(private, public []byte) error {
+	privateKey, err := x509.ParseECPrivateKey(private)
+	if err != nil {
+		return err
+	}
+
+	service.privateKey = privateKey
+
+	encodedKey := hex.EncodeToString(public)
+	service.encodedPubKey = encodedKey
+
+	publicKey, err := x509.ParsePKIXPublicKey(public)
+	if err != nil {
+		return err
+	}
+
+	service.publicKey = publicKey.(*ecdsa.PublicKey)
+
+	return nil
+}
+
+// GenerateKeyPair will create a new key pair using ECDSA.
+func (service *ECDSAService) GenerateKeyPair() ([]byte, []byte, error) {
+	pubkeyCurve := elliptic.P256()
+
+	privatekey, err := ecdsa.GenerateKey(pubkeyCurve, rand.Reader)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	service.privateKey = privatekey
+	service.publicKey = &privatekey.PublicKey
+
+	private, err := x509.MarshalECPrivateKey(service.privateKey)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	public, err := x509.MarshalPKIXPublicKey(service.publicKey)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	encodedKey := hex.EncodeToString(public)
+	service.encodedPubKey = encodedKey
+
+	return private, public, nil
+}
+
+// CreateSignature creates a digital signature.
+// It automatically hash a specific message using MD5 and creates a signature from
+// that hash.
+// If a secret is associated to the service, it will be used instead of the specified
+// message.
+// It then encodes the generated signature in base64.
+func (service *ECDSAService) CreateSignature(message string) (string, error) {
+	if service.secret != "" {
+		message = service.secret
+	}
+
+	hash := libcrypto.InsecureHashFromBytes([]byte(message))
+
+	r, s, err := ecdsa.Sign(rand.Reader, service.privateKey, hash)
+	if err != nil {
+		return "", err
+	}
+
+	keyBytes := service.privateKey.Params().BitSize / 8
+
+	rBytes := r.Bytes()
+	rBytesPadded := make([]byte, keyBytes)
+	copy(rBytesPadded[keyBytes-len(rBytes):], rBytes)
+
+	sBytes := s.Bytes()
+	sBytesPadded := make([]byte, keyBytes)
+	copy(sBytesPadded[keyBytes-len(sBytes):], sBytes)
+
+	signature := append(rBytesPadded, sBytesPadded...)
+
+	return base64.RawStdEncoding.EncodeToString(signature), nil
+}

api/crypto/ecdsa_test.go

@@ -0,0 +1,23 @@
+package crypto
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestCreateSignature(t *testing.T) {
+	t.Parallel()
+	var s = NewECDSAService("secret")
+
+	privKey, pubKey, err := s.GenerateKeyPair()
+	require.NoError(t, err)
+	require.NotEmpty(t, privKey)
+	require.NotEmpty(t, pubKey)
+
+	m := "test message"
+	r, err := s.CreateSignature(m)
+	require.NoError(t, err)
+	require.NotEqual(t, r, m)
+	require.NotEmpty(t, r)
+}

api/crypto/hash.go

@@ -0,0 +1,24 @@
+package crypto
+
+import (
+	// Not allowed in FIPS mode
+	"golang.org/x/crypto/bcrypt" //nolint:depguard
+)
+
+// Service represents a service for encrypting/hashing data.
+type Service struct{}
+
+// Hash hashes a string using the bcrypt algorithm
+func (Service) Hash(data string) (string, error) {
+	bytes, err := bcrypt.GenerateFromPassword([]byte(data), bcrypt.DefaultCost)
+	if err != nil {
+		return "", err
+	}
+
+	return string(bytes), err
+}
+
+// CompareHashAndData compares a hash to clear data and returns an error if the comparison fails.
+func (Service) CompareHashAndData(hash string, data string) error {
+	return bcrypt.CompareHashAndPassword([]byte(hash), []byte(data))
+}

api/crypto/hash_test.go

@@ -0,0 +1,65 @@
+package crypto
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestService_Hash(t *testing.T) {
+	t.Parallel()
+	var s = Service{}
+
+	type args struct {
+		hash string
+		data string
+	}
+	tests := []struct {
+		name   string
+		args   args
+		expect bool
+	}{
+		{
+			name: "Empty",
+			args: args{
+				hash: "",
+				data: "",
+			},
+			expect: false,
+		},
+		{
+			name: "Matching",
+			args: args{
+				hash: "$2a$10$6BFGd94oYx8k0bFNO6f33uPUpcpAJyg8UVX.akLe9EthF/ZBTXqcy",
+				data: "Passw0rd!",
+			},
+			expect: true,
+		},
+		{
+			name: "Not matching",
+			args: args{
+				hash: "$2a$10$ltKrUZ7492xyutHOb0/XweevU4jyw7QO66rP32jTVOMb3EX3JxA/a",
+				data: "Passw0rd!",
+			},
+			expect: false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+
+			err := s.CompareHashAndData(tt.args.hash, tt.args.data)
+			if (err != nil) == tt.expect {
+				t.Errorf("Service.CompareHashAndData() = %v", err)
+			}
+		})
+	}
+}
+
+func TestHash(t *testing.T) {
+	t.Parallel()
+	s := Service{}
+
+	hash, err := s.Hash("Passw0rd!")
+	require.NoError(t, err)
+	require.NotEmpty(t, hash)
+}

api/crypto/nonce.go

@@ -0,0 +1,62 @@
+package crypto
+
+import (
+	"crypto/rand"
+	"errors"
+	"io"
+	"slices"
+)
+
+type Nonce struct {
+	val []byte
+}
+
+func NewNonce(size int) *Nonce {
+	return &Nonce{val: make([]byte, size)}
+}
+
+// NewRandomNonce generates a new initial nonce with the lower byte set to a random value
+// This ensures there are plenty of nonce values available before rolling over
+// Based on ideas from the Secure Programming Cookbook for C and C++ by John Viega, Matt Messier
+// https://www.oreilly.com/library/view/secure-programming-cookbook/0596003943/ch04s09.html
+func NewRandomNonce(size int) (*Nonce, error) {
+	randomBytes := 1
+	if size <= randomBytes {
+		return nil, errors.New("nonce size must be greater than the number of random bytes")
+	}
+
+	randomPart := make([]byte, randomBytes)
+	if _, err := rand.Read(randomPart); err != nil {
+		return nil, err
+	}
+
+	zeroPart := make([]byte, size-randomBytes)
+	nonceVal := append(randomPart, zeroPart...)
+	return &Nonce{val: nonceVal}, nil
+}
+
+func (n *Nonce) Read(stream io.Reader) error {
+	_, err := io.ReadFull(stream, n.val)
+	return err
+}
+
+func (n *Nonce) Value() []byte {
+	return n.val
+}
+
+func (n *Nonce) Increment() error {
+	// Start incrementing from the least significant byte
+	for i := range slices.Backward(n.val) {
+		// Increment the current byte
+		n.val[i]++
+
+		// Check for overflow
+		if n.val[i] != 0 {
+			// No overflow, nonce is successfully incremented
+			return nil
+		}
+	}
+
+	// If we reach here, it means the nonce has overflowed
+	return errors.New("nonce overflow")
+}

api/crypto/tls.go

@@ -0,0 +1,124 @@
+package crypto
+
+import (
+	"crypto/tls"
+	"crypto/x509"
+	"os"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/pkg/fips"
+)
+
+// CreateTLSConfiguration creates a basic tls.Config with recommended TLS settings
+func CreateTLSConfiguration(insecureSkipVerify bool) *tls.Config { //nolint:forbidigo
+	return createTLSConfiguration(fips.FIPSMode(), insecureSkipVerify)
+}
+
+func createTLSConfiguration(fipsEnabled bool, insecureSkipVerify bool) *tls.Config { //nolint:forbidigo
+	if fipsEnabled {
+		return &tls.Config{ //nolint:forbidigo
+			MinVersion: tls.VersionTLS12,
+			MaxVersion: tls.VersionTLS13,
+			CipherSuites: []uint16{
+				tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
+				tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
+				tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
+				tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
+			},
+			CurvePreferences: []tls.CurveID{tls.CurveP256, tls.CurveP384, tls.CurveP521},
+		}
+	}
+
+	return &tls.Config{ //nolint:forbidigo
+		MinVersion: tls.VersionTLS12,
+		CipherSuites: []uint16{
+			tls.TLS_AES_128_GCM_SHA256,
+			tls.TLS_AES_256_GCM_SHA384,
+			tls.TLS_CHACHA20_POLY1305_SHA256,
+			tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
+			tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
+			tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
+			tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
+			tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
+			tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
+			tls.TLS_RSA_WITH_AES_128_GCM_SHA256,
+			tls.TLS_RSA_WITH_AES_256_GCM_SHA384,
+			tls.TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,
+			tls.TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,
+			tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
+			tls.TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
+			tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
+			tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,
+		},
+		InsecureSkipVerify: insecureSkipVerify, //nolint:forbidigo
+	}
+}
+
+// CreateTLSConfigurationFromBytes initializes a tls.Config using a CA certificate, a certificate and a key
+// loaded from memory.
+func CreateTLSConfigurationFromBytes(useTLS bool, caCert, cert, key []byte, skipClientVerification, skipServerVerification bool) (*tls.Config, error) { //nolint:forbidigo
+	return createTLSConfigurationFromBytes(fips.FIPSMode(), useTLS, caCert, cert, key, skipClientVerification, skipServerVerification)
+}
+
+func createTLSConfigurationFromBytes(fipsEnabled, useTLS bool, caCert, cert, key []byte, skipClientVerification, skipServerVerification bool) (*tls.Config, error) { //nolint:forbidigo
+	if !useTLS {
+		return nil, nil
+	}
+
+	config := createTLSConfiguration(fipsEnabled, skipServerVerification)
+
+	if !skipClientVerification || fipsEnabled {
+		certificate, err := tls.X509KeyPair(cert, key)
+		if err != nil {
+			return nil, err
+		}
+
+		config.Certificates = []tls.Certificate{certificate}
+	}
+
+	if !skipServerVerification || fipsEnabled {
+		caCertPool := x509.NewCertPool()
+		caCertPool.AppendCertsFromPEM(caCert)
+		config.RootCAs = caCertPool
+	}
+
+	return config, nil
+}
+
+// CreateTLSConfigurationFromDisk initializes a tls.Config using a CA certificate, a certificate and a key
+// loaded from disk.
+func CreateTLSConfigurationFromDisk(config portainer.TLSConfiguration) (*tls.Config, error) { //nolint:forbidigo
+	return createTLSConfigurationFromDisk(fips.FIPSMode(), config)
+}
+
+func createTLSConfigurationFromDisk(fipsEnabled bool, config portainer.TLSConfiguration) (*tls.Config, error) { //nolint:forbidigo
+	if !config.TLS && fipsEnabled {
+		return nil, fips.ErrTLSRequired
+	} else if !config.TLS {
+		return nil, nil
+	}
+
+	tlsConfig := createTLSConfiguration(fipsEnabled, config.TLSSkipVerify)
+
+	if config.TLSCertPath != "" && config.TLSKeyPath != "" {
+		cert, err := tls.LoadX509KeyPair(config.TLSCertPath, config.TLSKeyPath)
+		if err != nil {
+			return nil, err
+		}
+
+		tlsConfig.Certificates = []tls.Certificate{cert}
+	}
+
+	if !tlsConfig.InsecureSkipVerify && config.TLSCACertPath != "" { //nolint:forbidigo
+		caCert, err := os.ReadFile(config.TLSCACertPath)
+		if err != nil {
+			return nil, err
+		}
+
+		caCertPool := x509.NewCertPool()
+		caCertPool.AppendCertsFromPEM(caCert)
+		tlsConfig.RootCAs = caCertPool
+	}
+
+	return tlsConfig, nil
+}

api/crypto/tls_test.go

@@ -0,0 +1,92 @@
+package crypto
+
+import (
+	"crypto/tls"
+	"testing"
+
+	portainer "github.com/portainer/portainer/api"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestCreateTLSConfiguration(t *testing.T) {
+	t.Parallel()
+	// InsecureSkipVerify = false
+	config := CreateTLSConfiguration(false)
+	require.Equal(t, config.MinVersion, uint16(tls.VersionTLS12)) //nolint:forbidigo
+	require.False(t, config.InsecureSkipVerify)                   //nolint:forbidigo
+
+	// InsecureSkipVerify = true
+	config = CreateTLSConfiguration(true)
+	require.Equal(t, config.MinVersion, uint16(tls.VersionTLS12)) //nolint:forbidigo
+	require.True(t, config.InsecureSkipVerify)                    //nolint:forbidigo
+}
+
+func TestCreateTLSConfigurationFIPS(t *testing.T) {
+	t.Parallel()
+	fips := true
+
+	fipsCipherSuites := []uint16{
+		tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
+		tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
+		tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
+		tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
+	}
+
+	fipsCurvePreferences := []tls.CurveID{tls.CurveP256, tls.CurveP384, tls.CurveP521}
+
+	config := createTLSConfiguration(fips, false)
+	require.Equal(t, config.MinVersion, uint16(tls.VersionTLS12))   //nolint:forbidigo
+	require.Equal(t, config.MaxVersion, uint16(tls.VersionTLS13))   //nolint:forbidigo
+	require.Equal(t, config.CipherSuites, fipsCipherSuites)         //nolint:forbidigo
+	require.Equal(t, config.CurvePreferences, fipsCurvePreferences) //nolint:forbidigo
+	require.False(t, config.InsecureSkipVerify)                     //nolint:forbidigo
+}
+
+func TestCreateTLSConfigurationFromBytes(t *testing.T) {
+	t.Parallel()
+	// No TLS
+	config, err := CreateTLSConfigurationFromBytes(false, nil, nil, nil, false, false)
+	require.NoError(t, err)
+	require.Nil(t, config)
+
+	// Skip TLS client/server verifications
+	config, err = CreateTLSConfigurationFromBytes(true, nil, nil, nil, true, true)
+	require.NoError(t, err)
+	require.NotNil(t, config)
+
+	// Empty TLS
+	config, err = CreateTLSConfigurationFromBytes(true, nil, nil, nil, false, false)
+	require.Error(t, err)
+	require.Nil(t, config)
+}
+
+func TestCreateTLSConfigurationFromDisk(t *testing.T) {
+	t.Parallel()
+	// No TLS
+	config, err := CreateTLSConfigurationFromDisk(portainer.TLSConfiguration{})
+	require.NoError(t, err)
+	require.Nil(t, config)
+
+	// Skip TLS verifications
+	config, err = CreateTLSConfigurationFromDisk(portainer.TLSConfiguration{
+		TLS:           true,
+		TLSSkipVerify: true,
+	})
+	require.NoError(t, err)
+	require.NotNil(t, config)
+}
+
+func TestCreateTLSConfigurationFromDiskFIPS(t *testing.T) {
+	t.Parallel()
+	fips := true
+
+	// Skipping TLS verifications cannot be done in FIPS mode
+	config, err := createTLSConfigurationFromDisk(fips, portainer.TLSConfiguration{
+		TLS:           true,
+		TLSSkipVerify: true,
+	})
+	require.NoError(t, err)
+	require.NotNil(t, config)
+	require.False(t, config.InsecureSkipVerify) //nolint:forbidigo
+}

api/database/boltdb/db.go

@@ -0,0 +1,503 @@
+package boltdb
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"encoding/binary"
+	"errors"
+	"fmt"
+	"io"
+	"math"
+	"os"
+	"path"
+	"strconv"
+	"time"
+
+	portainer "github.com/portainer/portainer/api"
+	dserrors "github.com/portainer/portainer/api/dataservices/errors"
+
+	"github.com/rs/zerolog/log"
+	bolt "go.etcd.io/bbolt"
+)
+
+const (
+	DatabaseFileName          = "portainer.db"
+	EncryptedDatabaseFileName = "portainer.edb"
+
+	txMaxSize       = 65536
+	compactedSuffix = ".compacted"
+)
+
+var (
+	ErrHaveEncryptedAndUnencrypted = errors.New("Portainer has detected both an encrypted and un-encrypted database and cannot start.  Only one database should exist")
+	ErrHaveEncryptedWithNoKey      = errors.New("The portainer database is encrypted, but no secret was loaded")
+)
+
+type DbConnection struct {
+	Path            string
+	MaxBatchSize    int
+	MaxBatchDelay   time.Duration
+	InitialMmapSize int
+	EncryptionKey   []byte
+	isEncrypted     bool
+	Compact         bool
+
+	gcm cipher.AEAD
+
+	*bolt.DB
+}
+
+// GetDatabaseFileName get the database filename
+func (connection *DbConnection) GetDatabaseFileName() string {
+	if connection.IsEncryptedStore() {
+		return EncryptedDatabaseFileName
+	}
+
+	return DatabaseFileName
+}
+
+// GetDataseFilePath get the path + filename for the database file
+func (connection *DbConnection) GetDatabaseFilePath() string {
+	if connection.IsEncryptedStore() {
+		return path.Join(connection.Path, EncryptedDatabaseFileName)
+	}
+
+	return path.Join(connection.Path, DatabaseFileName)
+}
+
+// GetStorePath get the filename and path for the database file
+func (connection *DbConnection) GetStorePath() string {
+	return connection.Path
+}
+
+func (connection *DbConnection) GetDatabaseFileSize() (int64, error) {
+	file, err := os.Stat(connection.GetDatabaseFilePath())
+	if err != nil {
+		return 0, fmt.Errorf("Failed to stat database file path: %s err: %w", connection.GetDatabaseFilePath(), err)
+	}
+
+	return file.Size(), nil
+}
+
+func (connection *DbConnection) SetEncrypted(flag bool) error {
+	connection.isEncrypted = flag
+
+	if !flag || connection.EncryptionKey == nil {
+		connection.gcm = nil
+
+		return nil
+	}
+
+	block, err := aes.NewCipher(connection.EncryptionKey)
+	if err != nil {
+		return fmt.Errorf("creating AES cipher for database encryption: %w", err)
+	}
+
+	gcm, err := cipher.NewGCMWithRandomNonce(block)
+	if err != nil {
+		return fmt.Errorf("creating GCM cipher for database encryption: %w", err)
+	}
+
+	connection.gcm = gcm
+
+	return nil
+}
+
+// Return true if the database is encrypted
+func (connection *DbConnection) IsEncryptedStore() bool {
+	return connection.getEncryptionKey() != nil
+}
+
+// NeedsEncryptionMigration returns true if database encryption is enabled and
+// we have an un-encrypted DB that requires migration to an encrypted DB
+func (connection *DbConnection) NeedsEncryptionMigration() (bool, error) {
+	// Cases:  Note, we need to check both portainer.db and portainer.edb
+	// to determine if it's a new store.   We only need to differentiate between cases 2,3 and 5
+
+	// 1) portainer.edb + key     => False
+	// 2) portainer.edb + no key  => ERROR Fatal!
+	// 3) portainer.db  + key     => True  (needs migration)
+	// 4) portainer.db  + no key  => False
+	// 5) NoDB (new)    + key     => False
+	// 6) NoDB (new)    + no key  => False
+	// 7) portainer.db & portainer.edb => ERROR Fatal!
+
+	// If we have a loaded encryption key, always set encrypted
+	if connection.EncryptionKey != nil {
+		if err := connection.SetEncrypted(true); err != nil {
+			return false, err
+		}
+	}
+
+	// Check for portainer.db
+	dbFile := path.Join(connection.Path, DatabaseFileName)
+	_, err := os.Stat(dbFile)
+	haveDbFile := err == nil
+
+	// Check for portainer.edb
+	edbFile := path.Join(connection.Path, EncryptedDatabaseFileName)
+	_, err = os.Stat(edbFile)
+	haveEdbFile := err == nil
+
+	if haveDbFile && haveEdbFile {
+		// 7 - encrypted and unencrypted db?
+		return false, ErrHaveEncryptedAndUnencrypted
+	}
+
+	if haveDbFile && connection.EncryptionKey != nil {
+		// 3 - needs migration
+		return true, nil
+	}
+
+	if haveEdbFile && connection.EncryptionKey == nil {
+		// 2 - encrypted db, but no key?
+		return false, ErrHaveEncryptedWithNoKey
+	}
+
+	// 1, 4, 5, 6
+	return false, nil
+}
+
+// Open opens and initializes the BoltDB database.
+func (connection *DbConnection) Open() error {
+	log.Info().Str("filename", connection.GetDatabaseFileName()).Msg("loading PortainerDB")
+
+	databasePath := connection.GetDatabaseFilePath()
+	db, err := bolt.Open(databasePath, 0600, connection.boltOptions(connection.Compact))
+	if err != nil {
+		return err
+	}
+
+	db.MaxBatchSize = connection.MaxBatchSize
+	db.MaxBatchDelay = connection.MaxBatchDelay
+	connection.DB = db
+
+	if connection.Compact {
+		log.Info().Msg("compacting database")
+		if err := connection.compact(); err != nil {
+			log.Error().Err(err).Msg("failed to compact database")
+
+			// Close the read-only database and re-open in read-write mode
+			if err := connection.Close(); err != nil {
+				log.Warn().Err(err).Msg("failure to close the database after failed compaction")
+			}
+
+			connection.Compact = false
+
+			return connection.Open()
+		} else {
+			log.Info().Msg("database compaction completed")
+		}
+	}
+
+	return nil
+}
+
+// Close closes the BoltDB database.
+// Safe to being called multiple times.
+func (connection *DbConnection) Close() error {
+	log.Info().Msg("closing PortainerDB")
+
+	if connection.DB != nil {
+		return connection.DB.Close()
+	}
+
+	return nil
+}
+
+func (connection *DbConnection) txFn(fn func(portainer.Transaction) error) func(*bolt.Tx) error {
+	return func(tx *bolt.Tx) error {
+		return fn(&DbTransaction{conn: connection, tx: tx})
+	}
+}
+
+// UpdateTx executes the given function inside a read-write transaction
+func (connection *DbConnection) UpdateTx(fn func(portainer.Transaction) error) error {
+	if connection.MaxBatchDelay > 0 && connection.MaxBatchSize > 1 {
+		return connection.Batch(connection.txFn(fn))
+	}
+
+	return connection.Update(connection.txFn(fn))
+}
+
+// ViewTx executes the given function inside a read-only transaction
+func (connection *DbConnection) ViewTx(fn func(portainer.Transaction) error) error {
+	return connection.View(connection.txFn(fn))
+}
+
+// BackupTo backs up db to a provided writer.
+// It does hot backup and doesn't block other database reads and writes
+func (connection *DbConnection) BackupTo(w io.Writer) error {
+	return connection.View(func(tx *bolt.Tx) error {
+		_, err := tx.WriteTo(w)
+
+		return err
+	})
+}
+
+func (connection *DbConnection) ExportRaw(filename string) error {
+	databasePath := connection.GetDatabaseFilePath()
+	if _, err := os.Stat(databasePath); err != nil {
+		return fmt.Errorf("stat on %s failed, error: %w", databasePath, err)
+	}
+
+	b, err := connection.ExportJSON(databasePath, true)
+	if err != nil {
+		return err
+	}
+
+	return os.WriteFile(filename, b, 0600)
+}
+
+// ConvertToKey returns an 8-byte big endian representation of v.
+// This function is typically used for encoding integer IDs to byte slices
+// so that they can be used as BoltDB keys.
+func (connection *DbConnection) ConvertToKey(v int) []byte {
+	b := make([]byte, 8)
+	binary.BigEndian.PutUint64(b, uint64(v))
+
+	return b
+}
+
+// keyToString Converts a key to a string value suitable for logging
+func keyToString(b []byte) string {
+	if len(b) != 8 {
+		return string(b)
+	}
+
+	v := binary.BigEndian.Uint64(b)
+	if v <= math.MaxInt32 {
+		return strconv.FormatUint(v, 10)
+	}
+
+	return string(b)
+}
+
+// CreateBucket is a generic function used to create a bucket inside a database.
+func (connection *DbConnection) SetServiceName(bucketName string) error {
+	return connection.UpdateTx(func(tx portainer.Transaction) error {
+		return tx.SetServiceName(bucketName)
+	})
+}
+
+// GetObject is a generic function used to retrieve an unmarshalled object from a database.
+func (connection *DbConnection) GetObject(bucketName string, key []byte, object any) error {
+	return connection.ViewTx(func(tx portainer.Transaction) error {
+		return tx.GetObject(bucketName, key, object)
+	})
+}
+
+func (connection *DbConnection) GetRawBytes(bucketName string, key []byte) ([]byte, error) {
+	var value []byte
+
+	err := connection.ViewTx(func(tx portainer.Transaction) error {
+		var err error
+		value, err = tx.GetRawBytes(bucketName, key)
+
+		return err
+	})
+
+	return value, err
+}
+
+func (connection *DbConnection) KeyExists(bucketName string, key []byte) (bool, error) {
+	var exists bool
+
+	err := connection.ViewTx(func(tx portainer.Transaction) error {
+		var err error
+		exists, err = tx.KeyExists(bucketName, key)
+
+		return err
+	})
+
+	return exists, err
+}
+
+func (connection *DbConnection) getEncryptionKey() []byte {
+	if !connection.isEncrypted {
+		return nil
+	}
+
+	return connection.EncryptionKey
+}
+
+// UpdateObject is a generic function used to update an object inside a database.
+func (connection *DbConnection) UpdateObject(bucketName string, key []byte, object any) error {
+	return connection.UpdateTx(func(tx portainer.Transaction) error {
+		return tx.UpdateObject(bucketName, key, object)
+	})
+}
+
+// UpdateObjectFunc is a generic function used to update an object safely without race conditions.
+func (connection *DbConnection) UpdateObjectFunc(bucketName string, key []byte, object any, updateFn func()) error {
+	return connection.Batch(func(tx *bolt.Tx) error {
+		bucket := tx.Bucket([]byte(bucketName))
+
+		data := bucket.Get(key)
+		if data == nil {
+			return fmt.Errorf("%w (bucket=%s, key=%s)", dserrors.ErrObjectNotFound, bucketName, keyToString(key))
+		}
+
+		err := connection.UnmarshalObject(data, object)
+		if err != nil {
+			return err
+		}
+
+		updateFn()
+
+		data, err = connection.MarshalObject(object)
+		if err != nil {
+			return err
+		}
+
+		return bucket.Put(key, data)
+	})
+}
+
+// DeleteObject is a generic function used to delete an object inside a database.
+func (connection *DbConnection) DeleteObject(bucketName string, key []byte) error {
+	return connection.UpdateTx(func(tx portainer.Transaction) error {
+		return tx.DeleteObject(bucketName, key)
+	})
+}
+
+// DeleteAllObjects delete all objects where matching() returns (id, ok).
+// TODO: think about how to return the error inside (maybe change ok to type err, and use "notfound"?
+func (connection *DbConnection) DeleteAllObjects(bucketName string, obj any, matching func(o any) (id int, ok bool)) error {
+	return connection.UpdateTx(func(tx portainer.Transaction) error {
+		return tx.DeleteAllObjects(bucketName, obj, matching)
+	})
+}
+
+// GetNextIdentifier is a generic function that returns the specified bucket identifier incremented by 1.
+func (connection *DbConnection) GetNextIdentifier(bucketName string) int {
+	var identifier int
+
+	_ = connection.UpdateTx(func(tx portainer.Transaction) error {
+		identifier = tx.GetNextIdentifier(bucketName)
+		return nil
+	})
+
+	return identifier
+}
+
+// CreateObject creates a new object in the bucket, using the next bucket sequence id
+func (connection *DbConnection) CreateObject(bucketName string, fn func(uint64) (int, any)) error {
+	return connection.UpdateTx(func(tx portainer.Transaction) error {
+		return tx.CreateObject(bucketName, fn)
+	})
+}
+
+// CreateObjectWithId creates a new object in the bucket, using the specified id
+func (connection *DbConnection) CreateObjectWithId(bucketName string, id int, obj any) error {
+	return connection.UpdateTx(func(tx portainer.Transaction) error {
+		return tx.CreateObjectWithId(bucketName, id, obj)
+	})
+}
+
+// CreateObjectWithStringId creates a new object in the bucket, using the specified id
+func (connection *DbConnection) CreateObjectWithStringId(bucketName string, id []byte, obj any) error {
+	return connection.UpdateTx(func(tx portainer.Transaction) error {
+		return tx.CreateObjectWithStringId(bucketName, id, obj)
+	})
+}
+
+func (connection *DbConnection) GetAll(bucketName string, obj any, appendFn func(o any) (any, error)) error {
+	return connection.ViewTx(func(tx portainer.Transaction) error {
+		return tx.GetAll(bucketName, obj, appendFn)
+	})
+}
+
+func (connection *DbConnection) GetAllWithKeyPrefix(bucketName string, keyPrefix []byte, obj any, appendFn func(o any) (any, error)) error {
+	return connection.ViewTx(func(tx portainer.Transaction) error {
+		return tx.GetAllWithKeyPrefix(bucketName, keyPrefix, obj, appendFn)
+	})
+}
+
+// BackupMetadata will return a copy of the boltdb sequence numbers for all buckets.
+func (connection *DbConnection) BackupMetadata() (map[string]any, error) {
+	buckets := map[string]any{}
+
+	err := connection.View(func(tx *bolt.Tx) error {
+		return tx.ForEach(func(name []byte, bucket *bolt.Bucket) error {
+			bucketName := string(name)
+			seqId := bucket.Sequence()
+			buckets[bucketName] = int(seqId)
+
+			return nil
+		})
+	})
+
+	return buckets, err
+}
+
+// RestoreMetadata will restore the boltdb sequence numbers for all buckets.
+func (connection *DbConnection) RestoreMetadata(s map[string]any) error {
+	var err error
+
+	for bucketName, v := range s {
+		id, ok := v.(float64) // JSON ints are unmarshalled to interface as float64. See: https://pkg.go.dev/encoding/json#Decoder.Decode
+		if !ok {
+			log.Error().Str("bucket", bucketName).Msg("failed to restore metadata to bucket, skipped")
+
+			continue
+		}
+
+		err = connection.Batch(func(tx *bolt.Tx) error {
+			bucket, err := tx.CreateBucketIfNotExists([]byte(bucketName))
+			if err != nil {
+				return err
+			}
+
+			return bucket.SetSequence(uint64(id))
+		})
+	}
+
+	return err
+}
+
+// compact attempts to compact the database and replace it iff it succeeds
+func (connection *DbConnection) compact() (err error) {
+	compactedPath := connection.GetDatabaseFilePath() + compactedSuffix
+
+	if err := os.Remove(compactedPath); err != nil && !errors.Is(err, os.ErrNotExist) {
+		return fmt.Errorf("failure to remove an existing compacted database: %w", err)
+	}
+
+	compactedDB, err := bolt.Open(compactedPath, 0o600, connection.boltOptions(false))
+	if err != nil {
+		return fmt.Errorf("failure to create the compacted database: %w", err)
+	}
+
+	compactedDB.MaxBatchSize = connection.MaxBatchSize
+	compactedDB.MaxBatchDelay = connection.MaxBatchDelay
+
+	if err := bolt.Compact(compactedDB, connection.DB, txMaxSize); err != nil {
+		return fmt.Errorf("failure to compact the database: %w",
+			errors.Join(err, compactedDB.Close(), os.Remove(compactedPath)))
+	}
+
+	if err := os.Rename(compactedPath, connection.GetDatabaseFilePath()); err != nil {
+		return fmt.Errorf("failure to move the compacted database: %w",
+			errors.Join(err, compactedDB.Close(), os.Remove(compactedPath)))
+	}
+
+	if err := connection.Close(); err != nil {
+		log.Warn().Err(err).Msg("failure to close the database after compaction")
+	}
+
+	connection.DB = compactedDB
+
+	return nil
+}
+
+func (connection *DbConnection) boltOptions(readOnly bool) *bolt.Options {
+	return &bolt.Options{
+		Timeout:         1 * time.Second,
+		InitialMmapSize: connection.InitialMmapSize,
+		FreelistType:    bolt.FreelistMapType,
+		NoFreelistSync:  true,
+		ReadOnly:        readOnly,
+		NoStatistics:    true,
+	}
+}

api/database/boltdb/db_test.go

@@ -0,0 +1,252 @@
+package boltdb
+
+import (
+	"os"
+	"testing"
+
+	"github.com/portainer/portainer/api/filesystem"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.etcd.io/bbolt"
+)
+
+func Test_NeedsEncryptionMigration(t *testing.T) {
+	t.Parallel()
+	// Test the specific scenarios mentioned in NeedsEncryptionMigration
+
+	// i.e.
+	// Cases:  Note, we need to check both portainer.db and portainer.edb
+	// to determine if it's a new store.   We only need to differentiate between cases 2,3 and 5
+
+	// 1) portainer.edb + key     => False
+	// 2) portainer.edb + no key  => ERROR Fatal!
+	// 3) portainer.db  + key     => True  (needs migration)
+	// 4) portainer.db  + no key  => False
+	// 5) NoDB (new)    + key     => False
+	// 6) NoDB (new)    + no key  => False
+	// 7) portainer.db & portainer.edb (key not important) => ERROR Fatal!
+
+	is := assert.New(t)
+	dir := t.TempDir()
+
+	cases := []struct {
+		name         string
+		dbname       string
+		key          bool
+		expectError  error
+		expectResult bool
+	}{
+		{
+			name:         "portainer.edb + key",
+			dbname:       EncryptedDatabaseFileName,
+			key:          true,
+			expectError:  nil,
+			expectResult: false,
+		},
+		{
+			name:         "portainer.db + key (migration needed)",
+			dbname:       DatabaseFileName,
+			key:          true,
+			expectError:  nil,
+			expectResult: true,
+		},
+		{
+			name:         "portainer.db + no key",
+			dbname:       DatabaseFileName,
+			key:          false,
+			expectError:  nil,
+			expectResult: false,
+		},
+		{
+			name:         "NoDB (new) + key",
+			dbname:       "",
+			key:          false,
+			expectError:  nil,
+			expectResult: false,
+		},
+		{
+			name:         "NoDB (new) + no key",
+			dbname:       "",
+			key:          false,
+			expectError:  nil,
+			expectResult: false,
+		},
+
+		// error tests
+		{
+			name:         "portainer.edb + no key",
+			dbname:       EncryptedDatabaseFileName,
+			key:          false,
+			expectError:  ErrHaveEncryptedWithNoKey,
+			expectResult: false,
+		},
+		{
+			name:         "portainer.db & portainer.edb",
+			dbname:       "both",
+			key:          true,
+			expectError:  ErrHaveEncryptedAndUnencrypted,
+			expectResult: false,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			connection := DbConnection{Path: dir}
+
+			if tc.dbname == "both" {
+				// Special case.  If portainer.db and portainer.edb exist.
+				dbFile1 := filesystem.JoinPaths(connection.Path, DatabaseFileName)
+				f, _ := os.Create(dbFile1)
+
+				err := f.Close()
+				require.NoError(t, err)
+
+				defer func() {
+					err := os.Remove(dbFile1)
+					require.NoError(t, err)
+				}()
+
+				dbFile2 := filesystem.JoinPaths(connection.Path, EncryptedDatabaseFileName)
+				f, _ = os.Create(dbFile2)
+
+				err = f.Close()
+				require.NoError(t, err)
+
+				defer func() {
+					err := os.Remove(dbFile2)
+					require.NoError(t, err)
+				}()
+			} else if tc.dbname != "" {
+				dbFile := filesystem.JoinPaths(connection.Path, tc.dbname)
+				f, _ := os.Create(dbFile)
+
+				err := f.Close()
+				require.NoError(t, err)
+
+				defer func() {
+					err := os.Remove(dbFile)
+					require.NoError(t, err)
+				}()
+			}
+
+			if tc.key {
+				connection.EncryptionKey = secretToEncryptionKey("secret")
+			}
+
+			result, err := connection.NeedsEncryptionMigration()
+
+			is.Equal(tc.expectError, err, "Fatal Error failure. Test: %s", tc.name)
+			is.Equal(result, tc.expectResult, "Failed test: %s", tc.name)
+		})
+	}
+}
+
+func TestSetEncrypted_InvalidKeyReturnsError(t *testing.T) {
+	t.Parallel()
+
+	conn := DbConnection{EncryptionKey: []byte("bad")}
+	err := conn.SetEncrypted(true)
+	require.Error(t, err)
+	require.Nil(t, conn.gcm)
+}
+
+func TestSetEncrypted_NilKeyDoesNotSetGCM(t *testing.T) {
+	t.Parallel()
+
+	conn := DbConnection{}
+	err := conn.SetEncrypted(true)
+	require.NoError(t, err)
+	require.Nil(t, conn.gcm)
+}
+
+func TestSetEncrypted_EnableThenDisableStopsEncryption(t *testing.T) {
+	t.Parallel()
+
+	key := secretToEncryptionKey(passphrase)
+	conn := DbConnection{EncryptionKey: key}
+
+	err := conn.SetEncrypted(true)
+	require.NoError(t, err)
+	require.NotNil(t, conn.gcm)
+
+	err = conn.SetEncrypted(false)
+	require.NoError(t, err)
+	require.Nil(t, conn.gcm)
+
+	// MarshalObject must return plaintext after encryption is disabled
+	data, err := conn.MarshalObject("hello")
+	require.NoError(t, err)
+	require.Equal(t, "hello", string(data))
+}
+
+func TestNeedsEncryptionMigration_InvalidKeyError(t *testing.T) {
+	t.Parallel()
+
+	conn := DbConnection{
+		Path:          t.TempDir(),
+		EncryptionKey: []byte("bad"),
+	}
+
+	result, err := conn.NeedsEncryptionMigration()
+	require.Error(t, err)
+	require.False(t, result)
+}
+
+func TestDBCompaction(t *testing.T) {
+	t.Parallel()
+	db := &DbConnection{Path: t.TempDir()}
+
+	err := db.Open()
+	require.NoError(t, err)
+
+	err = db.Update(func(tx *bbolt.Tx) error {
+		b, err := tx.CreateBucketIfNotExists([]byte("testbucket"))
+		if err != nil {
+			return err
+		}
+
+		err = b.Put([]byte("key"), []byte("value"))
+		require.NoError(t, err)
+
+		return nil
+	})
+	require.NoError(t, err)
+
+	err = db.Close()
+	require.NoError(t, err)
+
+	// Reopen the DB to trigger compaction
+	db.Compact = true
+	err = db.Open()
+	require.NoError(t, err)
+
+	// Check that the data is still there
+	err = db.View(func(tx *bbolt.Tx) error {
+		b := tx.Bucket([]byte("testbucket"))
+		if b == nil {
+			return nil
+		}
+
+		val := b.Get([]byte("key"))
+		require.Equal(t, []byte("value"), val)
+
+		return nil
+	})
+	require.NoError(t, err)
+
+	err = db.Close()
+	require.NoError(t, err)
+
+	// Failures
+	compactedPath := db.GetDatabaseFilePath() + compactedSuffix
+	err = os.Mkdir(compactedPath, 0o755)
+	require.NoError(t, err)
+
+	f, err := os.Create(filesystem.JoinPaths(compactedPath, "somefile"))
+	require.NoError(t, err)
+	require.NoError(t, f.Close())
+
+	err = db.Open()
+	require.NoError(t, err)
+}

api/database/boltdb/export.go

@@ -0,0 +1,108 @@
+package boltdb
+
+import (
+	"time"
+
+	"github.com/portainer/portainer/api/logs"
+	"github.com/rs/zerolog/log"
+	"github.com/segmentio/encoding/json"
+	bolt "go.etcd.io/bbolt"
+)
+
+func backupMetadata(connection *bolt.DB) (map[string]any, error) {
+	buckets := map[string]any{}
+
+	err := connection.View(func(tx *bolt.Tx) error {
+		err := tx.ForEach(func(name []byte, bucket *bolt.Bucket) error {
+			bucketName := string(name)
+			seqId := bucket.Sequence()
+			buckets[bucketName] = int(seqId)
+			return nil
+		})
+
+		return err
+	})
+
+	return buckets, err
+}
+
+// ExportJSON creates a JSON representation from a DbConnection. You can include
+// the database's metadata or ignore it. Ensure the database is closed before
+// using this function.
+// inspired by github.com/konoui/boltdb-exporter (which has no license)
+// but very much simplified, based on how we use boltdb
+func (c *DbConnection) ExportJSON(databasePath string, metadata bool) ([]byte, error) {
+	log.Debug().Str("databasePath", databasePath).Msg("exportJson")
+
+	connection, err := bolt.Open(databasePath, 0600, &bolt.Options{Timeout: 1 * time.Second, ReadOnly: true, NoStatistics: true})
+	if err != nil {
+		return []byte("{}"), err
+	}
+	defer logs.CloseAndLogErr(connection)
+
+	backup := make(map[string]any)
+	if metadata {
+		meta, err := backupMetadata(connection)
+		if err != nil {
+			log.Error().Err(err).Msg("failed exporting metadata")
+		}
+
+		backup["__metadata"] = meta
+	}
+
+	if err := connection.View(func(tx *bolt.Tx) error {
+		return tx.ForEach(func(name []byte, bucket *bolt.Bucket) error {
+			bucketName := string(name)
+			var list []any
+			version := make(map[string]string)
+			cursor := bucket.Cursor()
+			for k, v := cursor.First(); k != nil; k, v = cursor.Next() {
+				if v == nil {
+					continue
+				}
+
+				var obj any
+				err := c.UnmarshalObject(v, &obj)
+				if err != nil {
+					log.Error().
+						Str("bucket", bucketName).
+						Str("object", string(v)).
+						Err(err).
+						Msg("failed to unmarshal")
+
+					obj = v
+				}
+
+				if bucketName == "version" {
+					version[string(k)] = string(v)
+				} else {
+					list = append(list, obj)
+				}
+			}
+
+			if bucketName == "version" {
+				backup[bucketName] = version
+				return nil
+			}
+
+			if bucketName == "ssl" ||
+				bucketName == "settings" ||
+				bucketName == "tunnel_server" {
+				backup[bucketName] = nil
+				if len(list) > 0 {
+					backup[bucketName] = list[0]
+				}
+
+				return nil
+			}
+
+			backup[bucketName] = list
+
+			return nil
+		})
+	}); err != nil {
+		return []byte("{}"), err
+	}
+
+	return json.MarshalIndent(backup, "", "  ")
+}

api/database/boltdb/json.go

@@ -0,0 +1,80 @@
+package boltdb
+
+import (
+	"bytes"
+	"crypto/cipher"
+
+	"github.com/pkg/errors"
+	"github.com/segmentio/encoding/json"
+)
+
+var errEncryptedStringTooShort = errors.New("encrypted string too short")
+
+// MarshalObject encodes an object to binary format
+func (connection *DbConnection) MarshalObject(object any) ([]byte, error) {
+	buf := &bytes.Buffer{}
+
+	// Special case for the VERSION bucket. Here we're not using json
+	if v, ok := object.(string); ok {
+		buf.WriteString(v)
+	} else {
+		enc := json.NewEncoder(buf)
+		enc.SetSortMapKeys(false)
+		enc.SetAppendNewline(false)
+
+		if err := enc.Encode(object); err != nil {
+			return nil, err
+		}
+	}
+
+	if connection.gcm == nil {
+		return buf.Bytes(), nil
+	}
+
+	return encrypt(buf.Bytes(), connection.gcm), nil
+}
+
+// UnmarshalObject decodes an object from binary data
+func (connection *DbConnection) UnmarshalObject(data []byte, object any) error {
+	var err error
+	if connection.gcm != nil {
+		data, err = decrypt(data, connection.gcm)
+		if err != nil {
+			return errors.Wrap(err, "Failed decrypting object")
+		}
+	}
+
+	if err := json.Unmarshal(data, object); err != nil {
+		// Special case for the VERSION bucket. Here we're not using json
+		// So we need to return it as a string
+		s, ok := object.(*string)
+		if !ok {
+			return errors.Wrap(err, "Failed unmarshalling object")
+		}
+
+		*s = string(data)
+	}
+
+	return err
+}
+
+func encrypt(plaintext []byte, gcm cipher.AEAD) []byte {
+	return gcm.Seal(nil, nil, plaintext, nil)
+}
+
+func decrypt(encrypted []byte, gcm cipher.AEAD) ([]byte, error) {
+	if string(encrypted) == "false" {
+		return []byte("false"), nil
+	}
+
+	if len(encrypted) < gcm.Overhead() {
+		return encrypted, errEncryptedStringTooShort
+	}
+
+	plaintextByte, err := gcm.Open(nil, nil, encrypted, nil)
+	if err != nil {
+		return encrypted, errors.Wrap(err, "Error decrypting text")
+	}
+
+	return plaintextByte, nil
+}

api/database/boltdb/json_test.go

@@ -0,0 +1,391 @@
+package boltdb
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"fmt"
+	"io"
+	"testing"
+
+	"github.com/google/uuid"
+	"github.com/pkg/errors"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const (
+	jsonobject = `{"LogoURL":"","BlackListedLabels":[],"AuthenticationMethod":1,"InternalAuthSettings": {"RequiredPasswordLength": 12}"LDAPSettings":{"AnonymousMode":true,"ReaderDN":"","URL":"","TLSConfig":{"TLS":false,"TLSSkipVerify":false},"StartTLS":false,"SearchSettings":[{"BaseDN":"","Filter":"","UserNameAttribute":""}],"GroupSearchSettings":[{"GroupBaseDN":"","GroupFilter":"","GroupAttribute":""}],"AutoCreateUsers":true},"OAuthSettings":{"ClientID":"","AccessTokenURI":"","AuthorizationURI":"","ResourceURI":"","RedirectURI":"","UserIdentifier":"","Scopes":"","OAuthAutoCreateUsers":false,"DefaultTeamID":0,"SSO":true,"LogoutURI":"","KubeSecretKey":"j0zLVtY/lAWBk62ByyF0uP80SOXaitsABP0TTJX8MhI="},"FeatureFlagSettings":{},"SnapshotInterval":"5m","TemplatesURL":"https://raw.githubusercontent.com/portainer/templates/master/templates-2.0.json","EdgeAgentCheckinInterval":5,"EnableEdgeComputeFeatures":false,"UserSessionTimeout":"8h","KubeconfigExpiry":"0","HelmRepositoryURL":"https://charts.bitnami.com/bitnami","KubectlShellImage":"portainer/kubectl-shell","DisplayDonationHeader":false,"DisplayExternalContributors":false,"EnableHostManagementFeatures":false,"AllowVolumeBrowserForRegularUsers":false,"AllowBindMountsForRegularUsers":false,"AllowPrivilegedModeForRegularUsers":false,"AllowHostNamespaceForRegularUsers":false,"AllowStackManagementForRegularUsers":false,"AllowDeviceMappingForRegularUsers":false,"AllowContainerCapabilitiesForRegularUsers":false}`
+	passphrase = "my secret key"
+)
+
+func secretToEncryptionKey(passphrase string) []byte {
+	hash := sha256.Sum256([]byte(passphrase))
+	return hash[:]
+}
+
+func Test_MarshalObjectUnencrypted(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	uuid := uuid.New()
+
+	tests := []struct {
+		object   any
+		expected string
+	}{
+		{
+			object:   nil,
+			expected: `null`,
+		},
+		{
+			object:   true,
+			expected: `true`,
+		},
+		{
+			object:   false,
+			expected: `false`,
+		},
+		{
+			object:   123,
+			expected: `123`,
+		},
+		{
+			object:   "456",
+			expected: "456",
+		},
+		{
+			object:   uuid,
+			expected: "\"" + uuid.String() + "\"",
+		},
+		{
+			object:   uuid.String(),
+			expected: uuid.String(),
+		},
+		{
+			object:   map[string]any{"key": "value"},
+			expected: `{"key":"value"}`,
+		},
+		{
+			object:   []bool{true, false},
+			expected: `[true,false]`,
+		},
+		{
+			object:   []int{1, 2, 3},
+			expected: `[1,2,3]`,
+		},
+		{
+			object:   []string{"1", "2", "3"},
+			expected: `["1","2","3"]`,
+		},
+		{
+			object:   []map[string]any{{"key1": "value1"}, {"key2": "value2"}},
+			expected: `[{"key1":"value1"},{"key2":"value2"}]`,
+		},
+		{
+			object:   []any{1, "2", false, map[string]any{"key1": "value1"}},
+			expected: `[1,"2",false,{"key1":"value1"}]`,
+		},
+	}
+
+	conn := DbConnection{}
+
+	for _, test := range tests {
+		t.Run(fmt.Sprintf("%s -> %s", test.object, test.expected), func(t *testing.T) {
+			data, err := conn.MarshalObject(test.object)
+			require.NoError(t, err)
+			is.Equal(test.expected, string(data))
+		})
+	}
+}
+
+func Test_UnMarshalObjectUnencrypted(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	// Based on actual data entering and what we expect out of the function
+
+	tests := []struct {
+		object   []byte
+		expected string
+	}{
+		{
+			object:   []byte(""),
+			expected: "",
+		},
+		{
+			object:   []byte("35"),
+			expected: "35",
+		},
+		{
+			// An unmarshalled byte string should return the same without error
+			object:   []byte("9ca4a1dd-a439-4593-b386-a7dfdc2e9fc6"),
+			expected: "9ca4a1dd-a439-4593-b386-a7dfdc2e9fc6",
+		},
+		{
+			// An un-marshalled json object string should return the same as a string without error also
+			object:   []byte(jsonobject),
+			expected: jsonobject,
+		},
+	}
+
+	conn := DbConnection{}
+
+	for _, test := range tests {
+		t.Run(fmt.Sprintf("%s -> %s", test.object, test.expected), func(t *testing.T) {
+			var object string
+			err := conn.UnmarshalObject(test.object, &object)
+			require.NoError(t, err)
+			is.Equal(test.expected, object)
+		})
+	}
+}
+
+func Test_ObjectMarshallingEncrypted(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	// Based on actual data entering and what we expect out of the function
+
+	tests := []struct {
+		object   []byte
+		expected string
+	}{
+		{
+			object: []byte(""),
+		},
+		{
+			object: []byte("35"),
+		},
+		{
+			// An unmarshalled byte string should return the same without error
+			object: []byte("9ca4a1dd-a439-4593-b386-a7dfdc2e9fc6"),
+		},
+		{
+			// An un-marshalled json object string should return the same as a string without error also
+			object: []byte(jsonobject),
+		},
+	}
+
+	key := secretToEncryptionKey(passphrase)
+	conn := DbConnection{EncryptionKey: key}
+	err := conn.SetEncrypted(true)
+	require.NoError(t, err)
+
+	for _, test := range tests {
+		t.Run(fmt.Sprintf("%s -> %s", test.object, test.expected), func(t *testing.T) {
+
+			data, err := conn.MarshalObject(test.object)
+			require.NoError(t, err)
+
+			var object []byte
+			err = conn.UnmarshalObject(data, &object)
+
+			require.NoError(t, err)
+			is.Equal(test.object, object)
+		})
+	}
+}
+
+func Test_NonceSources(t *testing.T) {
+	t.Parallel()
+	// ensure that the new go 1.24 NewGCMWithRandomNonce works correctly with
+	// the old way of creating and including the nonce
+
+	encryptOldFn := func(plaintext []byte, passphrase []byte) (encrypted []byte, err error) {
+		block, _ := aes.NewCipher(passphrase)
+		gcm, err := cipher.NewGCM(block)
+		if err != nil {
+			return encrypted, err
+		}
+
+		nonce := make([]byte, gcm.NonceSize())
+		if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
+			return encrypted, err
+		}
+
+		return gcm.Seal(nonce, nonce, plaintext, nil), nil
+	}
+
+	decryptOldFn := func(encrypted []byte, passphrase []byte) (plaintext []byte, err error) {
+		block, err := aes.NewCipher(passphrase)
+		if err != nil {
+			return encrypted, errors.Wrap(err, "Error creating cypher block")
+		}
+
+		gcm, err := cipher.NewGCM(block)
+		if err != nil {
+			return encrypted, errors.Wrap(err, "Error creating GCM")
+		}
+
+		nonceSize := gcm.NonceSize()
+		if len(encrypted) < nonceSize {
+			return encrypted, errEncryptedStringTooShort
+		}
+
+		nonce, ciphertextByteClean := encrypted[:nonceSize], encrypted[nonceSize:]
+
+		plaintext, err = gcm.Open(nil, nonce, ciphertextByteClean, nil)
+		if err != nil {
+			return encrypted, errors.Wrap(err, "Error decrypting text")
+		}
+
+		return plaintext, err
+	}
+
+	passphrase := make([]byte, 32)
+	_, err := io.ReadFull(rand.Reader, passphrase)
+	require.NoError(t, err)
+
+	block, err := aes.NewCipher(passphrase)
+	require.NoError(t, err)
+
+	gcm, err := cipher.NewGCMWithRandomNonce(block)
+	require.NoError(t, err)
+
+	junk := make([]byte, 1024)
+	_, err = io.ReadFull(rand.Reader, junk)
+	require.NoError(t, err)
+
+	junkEnc := make([]byte, base64.StdEncoding.EncodedLen(len(junk)))
+	base64.StdEncoding.Encode(junkEnc, junk)
+
+	cases := [][]byte{
+		[]byte("test"),
+		[]byte("35"),
+		[]byte("9ca4a1dd-a439-4593-b386-a7dfdc2e9fc6"),
+		[]byte(jsonobject),
+		passphrase,
+		junk,
+		junkEnc,
+	}
+
+	for _, plain := range cases {
+		var enc, dec []byte
+		var err error
+
+		enc, err = encryptOldFn(plain, passphrase)
+		require.NoError(t, err)
+
+		dec, err = decrypt(enc, gcm)
+		require.NoError(t, err)
+
+		require.Equal(t, plain, dec)
+
+		enc = encrypt(plain, gcm)
+
+		dec, err = decryptOldFn(enc, passphrase)
+		require.NoError(t, err)
+
+		require.Equal(t, plain, dec)
+	}
+}
+
+func TestDecrypt_FalseStringBypassesDecryption(t *testing.T) {
+	t.Parallel()
+
+	key := secretToEncryptionKey(passphrase)
+	block, err := aes.NewCipher(key)
+	require.NoError(t, err)
+
+	gcm, err := cipher.NewGCMWithRandomNonce(block)
+	require.NoError(t, err)
+
+	result, err := decrypt([]byte("false"), gcm)
+	require.NoError(t, err)
+	require.Equal(t, []byte("false"), result)
+}
+
+func TestDecrypt_ShortDataReturnsError(t *testing.T) {
+	t.Parallel()
+
+	key := secretToEncryptionKey(passphrase)
+	block, err := aes.NewCipher(key)
+	require.NoError(t, err)
+
+	gcm, err := cipher.NewGCMWithRandomNonce(block)
+	require.NoError(t, err)
+
+	short := []byte("short")
+	result, err := decrypt(short, gcm)
+	require.ErrorIs(t, err, errEncryptedStringTooShort)
+	require.Equal(t, short, result)
+}
+
+func TestDecrypt_CorruptDataReturnsError(t *testing.T) {
+	t.Parallel()
+
+	key := secretToEncryptionKey(passphrase)
+	block, err := aes.NewCipher(key)
+	require.NoError(t, err)
+
+	gcm, err := cipher.NewGCMWithRandomNonce(block)
+	require.NoError(t, err)
+
+	// 30 bytes passes the length check but fails authentication
+	corrupted := make([]byte, 30)
+	_, err = io.ReadFull(rand.Reader, corrupted)
+	require.NoError(t, err)
+
+	result, err := decrypt(corrupted, gcm)
+	require.Error(t, err)
+	require.Equal(t, corrupted, result)
+}
+
+// BenchmarkEncryptCachedCipher measures the new approach: cipher created once and reused.
+func BenchmarkEncryptCachedCipher(b *testing.B) {
+	key := secretToEncryptionKey(passphrase)
+	conn := DbConnection{EncryptionKey: key}
+	err := conn.SetEncrypted(true)
+	require.NoError(b, err)
+
+	data := []byte(jsonobject)
+
+	b.ResetTimer()
+
+	for b.Loop() {
+		_ = encrypt(data, conn.gcm)
+	}
+}
+
+// BenchmarkEncryptPerCallCipher measures the old approach: cipher created on every call.
+func BenchmarkEncryptPerCallCipher(b *testing.B) {
+	key := secretToEncryptionKey(passphrase)
+	data := []byte(jsonobject)
+
+	b.ResetTimer()
+
+	for b.Loop() {
+		block, err := aes.NewCipher(key)
+		if err != nil {
+			b.Fatal(err)
+		}
+
+		gcm, err := cipher.NewGCMWithRandomNonce(block)
+		if err != nil {
+			b.Fatal(err)
+		}
+
+		_ = gcm.Seal(nil, nil, data, nil)
+	}
+}
+
+// BenchmarkEncryptCachedCipherParallel verifies the cached cipher is safe for concurrent use.
+func BenchmarkEncryptCachedCipherParallel(b *testing.B) {
+	key := secretToEncryptionKey(passphrase)
+	conn := DbConnection{EncryptionKey: key}
+	err := conn.SetEncrypted(true)
+	require.NoError(b, err)
+
+	data := []byte(jsonobject)
+
+	b.ResetTimer()
+
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			_ = encrypt(data, conn.gcm)
+		}
+	})
+}

api/database/boltdb/tx.go

@@ -0,0 +1,179 @@
+package boltdb
+
+import (
+	"bytes"
+	"fmt"
+
+	dserrors "github.com/portainer/portainer/api/dataservices/errors"
+
+	"github.com/pkg/errors"
+	"github.com/rs/zerolog/log"
+	bolt "go.etcd.io/bbolt"
+)
+
+type DbTransaction struct {
+	conn *DbConnection
+	tx   *bolt.Tx
+}
+
+func (tx *DbTransaction) SetServiceName(bucketName string) error {
+	_, err := tx.tx.CreateBucketIfNotExists([]byte(bucketName))
+	return err
+}
+
+func (tx *DbTransaction) GetObject(bucketName string, key []byte, object any) error {
+	bucket := tx.tx.Bucket([]byte(bucketName))
+
+	value := bucket.Get(key)
+	if value == nil {
+		return fmt.Errorf("%w (bucket=%s, key=%s)", dserrors.ErrObjectNotFound, bucketName, keyToString(key))
+	}
+
+	return tx.conn.UnmarshalObject(value, object)
+}
+
+func (tx *DbTransaction) GetRawBytes(bucketName string, key []byte) ([]byte, error) {
+	bucket := tx.tx.Bucket([]byte(bucketName))
+
+	value := bucket.Get(key)
+	if value == nil {
+		return nil, fmt.Errorf("%w (bucket=%s, key=%s)", dserrors.ErrObjectNotFound, bucketName, keyToString(key))
+	}
+
+	if tx.conn.gcm != nil {
+		var err error
+
+		if value, err = decrypt(value, tx.conn.gcm); err != nil {
+			return value, errors.Wrap(err, "Failed decrypting object")
+		}
+	}
+
+	return value, nil
+}
+
+func (tx *DbTransaction) KeyExists(bucketName string, key []byte) (bool, error) {
+	bucket := tx.tx.Bucket([]byte(bucketName))
+
+	value := bucket.Get(key)
+
+	return value != nil, nil
+}
+
+func (tx *DbTransaction) UpdateObject(bucketName string, key []byte, object any) error {
+	data, err := tx.conn.MarshalObject(object)
+	if err != nil {
+		return err
+	}
+
+	bucket := tx.tx.Bucket([]byte(bucketName))
+	return bucket.Put(key, data)
+}
+
+func (tx *DbTransaction) DeleteObject(bucketName string, key []byte) error {
+	bucket := tx.tx.Bucket([]byte(bucketName))
+	return bucket.Delete(key)
+}
+
+func (tx *DbTransaction) DeleteAllObjects(bucketName string, obj any, matchingFn func(o any) (id int, ok bool)) error {
+	var ids []int
+
+	bucket := tx.tx.Bucket([]byte(bucketName))
+
+	cursor := bucket.Cursor()
+	for k, v := cursor.First(); k != nil; k, v = cursor.Next() {
+		err := tx.conn.UnmarshalObject(v, &obj)
+		if err != nil {
+			return err
+		}
+
+		if id, ok := matchingFn(obj); ok {
+			ids = append(ids, id)
+		}
+	}
+
+	for _, id := range ids {
+		if err := bucket.Delete(tx.conn.ConvertToKey(id)); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (tx *DbTransaction) GetNextIdentifier(bucketName string) int {
+	bucket := tx.tx.Bucket([]byte(bucketName))
+
+	id, err := bucket.NextSequence()
+	if err != nil {
+		log.Error().Err(err).Str("bucket", bucketName).Msg("failed to get the next identifier")
+
+		return 0
+	}
+
+	return int(id)
+}
+
+func (tx *DbTransaction) CreateObject(bucketName string, fn func(uint64) (int, any)) error {
+	bucket := tx.tx.Bucket([]byte(bucketName))
+
+	seqId, _ := bucket.NextSequence()
+	id, obj := fn(seqId)
+
+	data, err := tx.conn.MarshalObject(obj)
+	if err != nil {
+		return err
+	}
+
+	return bucket.Put(tx.conn.ConvertToKey(id), data)
+}
+
+func (tx *DbTransaction) CreateObjectWithId(bucketName string, id int, obj any) error {
+	bucket := tx.tx.Bucket([]byte(bucketName))
+	data, err := tx.conn.MarshalObject(obj)
+	if err != nil {
+		return err
+	}
+
+	return bucket.Put(tx.conn.ConvertToKey(id), data)
+}
+
+func (tx *DbTransaction) CreateObjectWithStringId(bucketName string, id []byte, obj any) error {
+	bucket := tx.tx.Bucket([]byte(bucketName))
+	data, err := tx.conn.MarshalObject(obj)
+	if err != nil {
+		return err
+	}
+
+	return bucket.Put(id, data)
+}
+
+func (tx *DbTransaction) GetAll(bucketName string, obj any, appendFn func(o any) (any, error)) error {
+	bucket := tx.tx.Bucket([]byte(bucketName))
+
+	return bucket.ForEach(func(k []byte, v []byte) error {
+		err := tx.conn.UnmarshalObject(v, obj)
+		if err == nil {
+			obj, err = appendFn(obj)
+		}
+
+		return err
+	})
+}
+
+func (tx *DbTransaction) GetAllWithKeyPrefix(bucketName string, keyPrefix []byte, obj any, appendFn func(o any) (any, error)) error {
+	cursor := tx.tx.Bucket([]byte(bucketName)).Cursor()
+
+	for k, v := cursor.Seek(keyPrefix); k != nil && bytes.HasPrefix(k, keyPrefix); k, v = cursor.Next() {
+		err := tx.conn.UnmarshalObject(v, obj)
+		if err != nil {
+			return err
+		}
+
+		obj, err = appendFn(obj)
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}

api/database/boltdb/tx_test.go

@@ -0,0 +1,160 @@
+package boltdb
+
+import (
+	"errors"
+	"strconv"
+	"testing"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+	"github.com/stretchr/testify/require"
+)
+
+const testBucketName = "test-bucket"
+const testId = 1234
+
+type testStruct struct {
+	Key   string
+	Value string
+}
+
+func TestTxs(t *testing.T) {
+	t.Parallel()
+	conn := DbConnection{Path: t.TempDir()}
+
+	err := conn.Open()
+	require.NoError(t, err)
+	t.Cleanup(func() {
+		err := conn.Close()
+		require.NoError(t, err)
+	})
+
+	// Error propagation
+	err = conn.UpdateTx(func(tx portainer.Transaction) error {
+		return errors.New("this is an error")
+	})
+	require.Error(t, err)
+
+	// Create an object
+	newObj := testStruct{Key: "key", Value: "value"}
+
+	err = conn.UpdateTx(func(tx portainer.Transaction) error {
+		if err := tx.SetServiceName(testBucketName); err != nil {
+			return err
+		}
+
+		return tx.CreateObjectWithId(testBucketName, testId, newObj)
+	})
+	require.NoError(t, err)
+
+	obj := testStruct{}
+	err = conn.ViewTx(func(tx portainer.Transaction) error {
+		return tx.GetObject(testBucketName, conn.ConvertToKey(testId), &obj)
+	})
+	require.NoError(t, err)
+
+	if obj.Key != newObj.Key || obj.Value != newObj.Value {
+		t.Fatalf("expected %s:%s, got %s:%s instead", newObj.Key, newObj.Value, obj.Key, obj.Value)
+	}
+
+	// Update an object
+	updatedObj := testStruct{Key: "updated-key", Value: "updated-value"}
+
+	err = conn.UpdateTx(func(tx portainer.Transaction) error {
+		return tx.UpdateObject(testBucketName, conn.ConvertToKey(testId), &updatedObj)
+	})
+	require.NoError(t, err)
+
+	err = conn.ViewTx(func(tx portainer.Transaction) error {
+		return tx.GetObject(testBucketName, conn.ConvertToKey(testId), &obj)
+	})
+	require.NoError(t, err)
+
+	if obj.Key != updatedObj.Key || obj.Value != updatedObj.Value {
+		t.Fatalf("expected %s:%s, got %s:%s instead", updatedObj.Key, updatedObj.Value, obj.Key, obj.Value)
+	}
+
+	// Delete an object
+	err = conn.UpdateTx(func(tx portainer.Transaction) error {
+		return tx.DeleteObject(testBucketName, conn.ConvertToKey(testId))
+	})
+	require.NoError(t, err)
+
+	err = conn.ViewTx(func(tx portainer.Transaction) error {
+		return tx.GetObject(testBucketName, conn.ConvertToKey(testId), &obj)
+	})
+	require.True(t, dataservices.IsErrObjectNotFound(err))
+
+	// Get next identifier
+	err = conn.UpdateTx(func(tx portainer.Transaction) error {
+		id1 := tx.GetNextIdentifier(testBucketName)
+		id2 := tx.GetNextIdentifier(testBucketName)
+
+		if id1+1 != id2 {
+			return errors.New("unexpected identifier sequence")
+		}
+
+		return nil
+	})
+	require.NoError(t, err)
+
+	// Try to write in a read transaction
+	err = conn.ViewTx(func(tx portainer.Transaction) error {
+		return tx.CreateObjectWithId(testBucketName, testId, newObj)
+	})
+	require.Error(t, err)
+}
+
+func BenchmarkGetAll(b *testing.B) {
+	const endpointBucket = "endpoints"
+	const n = 10000
+
+	conn := DbConnection{Path: b.TempDir()}
+
+	err := conn.Open()
+	require.NoError(b, err)
+	b.Cleanup(func() {
+		err := conn.Close()
+		require.NoError(b, err)
+	})
+
+	err = conn.UpdateTx(func(tx portainer.Transaction) error {
+		if err := tx.SetServiceName(endpointBucket); err != nil {
+			return err
+		}
+
+		for i := 1; i <= n; i++ {
+			ep := portainer.Endpoint{
+				ID:              portainer.EndpointID(i),
+				Name:            "env-" + strconv.Itoa(i),
+				Type:            portainer.DockerEnvironment,
+				URL:             "tcp://192.168.1." + strconv.Itoa(i%254+1) + ":2375",
+				PublicURL:       "https://env-" + strconv.Itoa(i) + ".example.com",
+				GroupID:         portainer.EndpointGroupID(i%10 + 1),
+				TagIDs:          []portainer.TagID{portainer.TagID(i%5 + 1), portainer.TagID(i%3 + 1)},
+				LastCheckInDate: int64(i) * 1000,
+				EdgeID:          "edge-" + strconv.Itoa(i),
+			}
+
+			if err := tx.CreateObjectWithId(endpointBucket, i, &ep); err != nil {
+				return err
+			}
+		}
+
+		return nil
+	})
+	require.NoError(b, err)
+
+	b.ResetTimer()
+	b.ReportAllocs()
+
+	for b.Loop() {
+		var collection []portainer.Endpoint
+
+		if err := conn.ViewTx(func(tx portainer.Transaction) error {
+			return tx.GetAll(endpointBucket, new(portainer.Endpoint), dataservices.AppendFn(&collection))
+		}); err != nil {
+			b.Fatal(err)
+		}
+	}
+}

api/database/database.go

@@ -0,0 +1,21 @@
+package database
+
+import (
+	"fmt"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/database/boltdb"
+)
+
+// NewDatabase should use config options to return a connection to the requested database
+func NewDatabase(storeType, storePath string, encryptionKey []byte, compact bool) (connection portainer.Connection, err error) {
+	if storeType == "boltdb" {
+		return &boltdb.DbConnection{
+			Path:          storePath,
+			EncryptionKey: encryptionKey,
+			Compact:       compact,
+		}, nil
+	}
+
+	return nil, fmt.Errorf("Unknown storage database: %s", storeType)
+}

api/database/database_test.go

@@ -0,0 +1,25 @@
+package database
+
+import (
+	"testing"
+
+	"github.com/portainer/portainer/api/database/boltdb"
+	"github.com/portainer/portainer/api/filesystem"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewDatabase(t *testing.T) {
+	t.Parallel()
+	dbPath := filesystem.JoinPaths(t.TempDir(), "test.db")
+	connection, err := NewDatabase("boltdb", dbPath, nil, false)
+	require.NoError(t, err)
+	require.NotNil(t, connection)
+
+	_, ok := connection.(*boltdb.DbConnection)
+	require.True(t, ok)
+
+	connection, err = NewDatabase("unknown", dbPath, nil, false)
+	require.Error(t, err)
+	require.Nil(t, connection)
+}

api/database/models/version.go

@@ -0,0 +1,8 @@
+package models
+
+type Version struct {
+	SchemaVersion string
+	MigratorCount int
+	Edition       int
+	InstanceID    string
+}

api/dataservices/allowlist/allowlist.go

@@ -0,0 +1,131 @@
+package allowlist
+
+import (
+	"fmt"
+
+	lru "github.com/hashicorp/golang-lru"
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+	"github.com/portainer/portainer/pkg/libhttp/ssrf"
+)
+
+const (
+	BucketName = "allowlist"
+)
+
+type Service struct {
+	baseService dataservices.BaseDataService[portainer.AllowList, portainer.AllowListKey]
+	cache       *lru.Cache
+}
+
+func (service *Service) BucketName() string {
+	return service.baseService.BucketName()
+}
+
+func NewService(connection portainer.Connection) (*Service, error) {
+	err := connection.SetServiceName(BucketName)
+	if err != nil {
+		return nil, err
+	}
+
+	service := &Service{
+		baseService: dataservices.BaseDataService[portainer.AllowList, portainer.AllowListKey]{
+			Bucket:     BucketName,
+			Connection: connection,
+		},
+	}
+
+	err = service.populateCache()
+
+	return service, err
+}
+
+func (service *Service) populateCache() error {
+	allowListKeys := []portainer.AllowListKey{portainer.AllowListSSRF}
+	cache, err := lru.New(len(allowListKeys))
+	if err != nil {
+		return err
+	}
+
+	for _, k := range allowListKeys {
+		allowList, err := service.baseService.Read(k)
+		if dataservices.IsErrObjectNotFound(err) {
+			allowList = &portainer.AllowList{
+				ID:      k,
+				Mode:    portainer.SSRFModeOff,
+				Entries: []string{},
+			}
+		} else if err != nil {
+			return err
+		}
+
+		parsedAllowList := ssrf.ParseAllowedHosts(allowList.Entries)
+		parsedAllowList.Mode = allowList.Mode
+
+		cache.Add(k, &parsedAllowList)
+	}
+
+	service.cache = cache
+
+	return nil
+}
+
+func (service *Service) Tx(tx portainer.Transaction) *ServiceTx {
+	return &ServiceTx{
+		baseService: service.baseService.Tx(tx),
+		cache:       service.cache,
+	}
+}
+
+func (service *Service) Read(id portainer.AllowListKey) (*portainer.AllowList, error) {
+	var result *portainer.AllowList
+	if err := service.baseService.Connection.ViewTx(func(tx portainer.Transaction) error {
+		var err error
+		result, err = service.Tx(tx).Read(id)
+		return err
+	}); err != nil {
+		return nil, err
+	}
+
+	return result, nil
+}
+
+func (service *Service) ReadAll() ([]portainer.AllowList, error) {
+	var result []portainer.AllowList
+	if err := service.baseService.Connection.ViewTx(func(tx portainer.Transaction) error {
+		var err error
+		result, err = service.Tx(tx).ReadAll()
+		return err
+	}); err != nil {
+		return nil, err
+	}
+
+	return result, nil
+}
+
+func (service *Service) ReadParsed(id portainer.AllowListKey) (*portainer.ParsedAllowList, error) {
+	allowListAny, ok := service.cache.Get(id)
+	if ok {
+		allowList, ok := allowListAny.(*portainer.ParsedAllowList)
+		if !ok {
+			return nil, fmt.Errorf("expected ParsedAllowList in cache but got %T", allowListAny)
+		}
+
+		return allowList, nil
+	}
+
+	var result *portainer.ParsedAllowList
+	err := service.baseService.Connection.ViewTx(func(tx portainer.Transaction) error {
+		var err error
+		result, err = service.Tx(tx).ReadParsed(id)
+		return err
+	})
+
+	return result, err
+}
+
+func (service *Service) Update(id portainer.AllowListKey, allowList *portainer.AllowList) error {
+	return service.baseService.Connection.UpdateTx(func(tx portainer.Transaction) error {
+		return service.Tx(tx).Update(id, allowList)
+	})
+}

api/dataservices/allowlist/allowlist_test.go

@@ -0,0 +1,89 @@
+package allowlist_test
+
+import (
+	"net"
+	"testing"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/datastore"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAllowListReadEmpty(t *testing.T) {
+	t.Parallel()
+	_, ds := datastore.MustNewTestStore(t, false, false)
+	got, err := ds.AllowList().Read(portainer.AllowListSSRF)
+	expected := &portainer.AllowList{
+		ID:      portainer.AllowListSSRF,
+		Mode:    portainer.SSRFModeOff,
+		Entries: []string{},
+	}
+	require.NoError(t, err)
+	require.Equal(t, expected, got)
+}
+
+func TestAllowListUpdate(t *testing.T) {
+	t.Parallel()
+	_, ds := datastore.MustNewTestStore(t, false, false)
+
+	expected := &portainer.AllowList{
+		ID:      portainer.AllowListSSRF,
+		Mode:    portainer.SSRFModeEnforce,
+		Entries: []string{"example.com", "10.0.0.0/8"},
+	}
+
+	require.NoError(t, ds.AllowList().Update(portainer.AllowListSSRF, expected))
+
+	got, err := ds.AllowList().Read(portainer.AllowListSSRF)
+	require.NoError(t, err)
+	require.Equal(t, expected, got)
+}
+
+func TestAllowListReadAllEmpty(t *testing.T) {
+	t.Parallel()
+	_, ds := datastore.MustNewTestStore(t, false, false)
+
+	got, err := ds.AllowList().ReadAll()
+	require.NoError(t, err)
+	require.Equal(t, []portainer.AllowList{}, got)
+}
+
+func TestAllowListReadAllAfterUpdate(t *testing.T) {
+	t.Parallel()
+	_, ds := datastore.MustNewTestStore(t, false, false)
+
+	expected := portainer.AllowList{
+		ID:      portainer.AllowListSSRF,
+		Mode:    portainer.SSRFModeEnforce,
+		Entries: []string{"example.com", "10.0.0.0/8"},
+	}
+
+	require.NoError(t, ds.AllowList().Update(portainer.AllowListSSRF, &expected))
+
+	got, err := ds.AllowList().ReadAll()
+	require.NoError(t, err)
+	require.Equal(t, []portainer.AllowList{expected}, got)
+}
+
+func TestAllowListReadParsedAfterUpdate(t *testing.T) {
+	t.Parallel()
+	_, ds := datastore.MustNewTestStore(t, false, false)
+
+	require.NoError(t, ds.AllowList().Update(portainer.AllowListSSRF, &portainer.AllowList{
+		ID:      portainer.AllowListSSRF,
+		Mode:    portainer.SSRFModeEnforce,
+		Entries: []string{"example.com"},
+	}))
+
+	expected := &portainer.ParsedAllowList{
+		Mode: portainer.SSRFModeEnforce,
+		Nets: []*net.IPNet{},
+		Hosts: map[string]bool{
+			"example.com": true,
+		},
+	}
+
+	got, err := ds.AllowList().ReadParsed(portainer.AllowListSSRF)
+	require.NoError(t, err)
+	require.Equal(t, expected, got)
+}

api/dataservices/allowlist/tx.go

@@ -0,0 +1,77 @@
+package allowlist
+
+import (
+	"fmt"
+
+	lru "github.com/hashicorp/golang-lru"
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+	"github.com/portainer/portainer/pkg/libhttp/ssrf"
+)
+
+type ServiceTx struct {
+	baseService dataservices.BaseDataServiceTx[portainer.AllowList, portainer.AllowListKey]
+	cache       *lru.Cache
+}
+
+func (service *ServiceTx) BucketName() string {
+	return service.baseService.BucketName()
+}
+
+func (service *ServiceTx) ReadParsed(id portainer.AllowListKey) (*portainer.ParsedAllowList, error) {
+	allowListAny, ok := service.cache.Get(id)
+	if ok {
+		allowList, ok := allowListAny.(*portainer.ParsedAllowList)
+		if !ok {
+			return nil, fmt.Errorf("expected ParsedAllowList in cache but got %T", allowListAny)
+		}
+
+		return allowList, nil
+	}
+
+	allowList, err := service.Read(id)
+	if err != nil {
+		return nil, err
+	}
+
+	parsed := ssrf.ParseAllowedHosts(allowList.Entries)
+	parsed.Mode = allowList.Mode
+	service.cache.Add(id, &parsed)
+
+	return &parsed, nil
+}
+
+func (service *ServiceTx) Read(id portainer.AllowListKey) (*portainer.AllowList, error) {
+	allowList, err := service.baseService.Read(id)
+	if dataservices.IsErrObjectNotFound(err) {
+		allowList = &portainer.AllowList{
+			ID:      id,
+			Mode:    portainer.SSRFModeOff,
+			Entries: []string{},
+		}
+	} else if err != nil {
+		return nil, err
+	}
+
+	return allowList, nil
+}
+
+func (service *ServiceTx) ReadAll() ([]portainer.AllowList, error) {
+	allowLists, err := service.baseService.ReadAll()
+	if err != nil && !dataservices.IsErrObjectNotFound(err) {
+		return nil, err
+	}
+
+	return allowLists, nil
+}
+
+func (service *ServiceTx) Update(id portainer.AllowListKey, allowList *portainer.AllowList) error {
+	if err := service.baseService.Update(id, allowList); err != nil {
+		return err
+	}
+
+	parsed := ssrf.ParseAllowedHosts(allowList.Entries)
+	parsed.Mode = allowList.Mode
+	service.cache.Add(id, &parsed)
+	return nil
+}

api/dataservices/allowlist/tx_test.go

@@ -0,0 +1,92 @@
+package allowlist_test
+
+import (
+	"testing"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+	"github.com/portainer/portainer/api/datastore"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAllowListReadTx(t *testing.T) {
+	t.Parallel()
+	_, ds := datastore.MustNewTestStore(t, false, false)
+
+	var got *portainer.AllowList
+	require.NoError(t, ds.ViewTx(func(tx dataservices.DataStoreTx) error {
+		var err error
+		got, err = tx.AllowList().Read(portainer.AllowListSSRF)
+		return err
+	}))
+
+	expected := &portainer.AllowList{
+		ID:      portainer.AllowListSSRF,
+		Mode:    portainer.SSRFModeOff,
+		Entries: []string{},
+	}
+
+	require.Equal(t, expected, got)
+}
+
+func TestAllowListReadAllEmptyTx(t *testing.T) {
+	t.Parallel()
+	_, ds := datastore.MustNewTestStore(t, false, false)
+
+	var got []portainer.AllowList
+	require.NoError(t, ds.ViewTx(func(tx dataservices.DataStoreTx) error {
+		var err error
+		got, err = tx.AllowList().ReadAll()
+		return err
+	}))
+
+	require.Equal(t, []portainer.AllowList{}, got)
+}
+
+func TestAllowListReadAllAfterUpdateTx(t *testing.T) {
+	t.Parallel()
+	_, ds := datastore.MustNewTestStore(t, false, false)
+
+	expected := portainer.AllowList{
+		ID:      portainer.AllowListSSRF,
+		Mode:    portainer.SSRFModeEnforce,
+		Entries: []string{"example.com"},
+	}
+
+	require.NoError(t, ds.UpdateTx(func(tx dataservices.DataStoreTx) error {
+		return tx.AllowList().Update(portainer.AllowListSSRF, &expected)
+	}))
+
+	var got []portainer.AllowList
+	require.NoError(t, ds.ViewTx(func(tx dataservices.DataStoreTx) error {
+		var err error
+		got, err = tx.AllowList().ReadAll()
+		return err
+	}))
+
+	require.Equal(t, []portainer.AllowList{expected}, got)
+}
+
+func TestAllowListUpdateTx(t *testing.T) {
+	t.Parallel()
+	_, ds := datastore.MustNewTestStore(t, false, false)
+
+	expected := &portainer.AllowList{
+		ID:      portainer.AllowListSSRF,
+		Mode:    portainer.SSRFModeEnforce,
+		Entries: []string{"example.com"},
+	}
+
+	require.NoError(t, ds.UpdateTx(func(tx dataservices.DataStoreTx) error {
+		return tx.AllowList().Update(portainer.AllowListSSRF, expected)
+	}))
+
+	var got *portainer.AllowList
+	require.NoError(t, ds.ViewTx(func(tx dataservices.DataStoreTx) error {
+		var err error
+		got, err = tx.AllowList().Read(portainer.AllowListSSRF)
+		return err
+	}))
+
+	require.Equal(t, expected, got)
+}

api/dataservices/apikeyrepository/apikeyrepository.go

@@ -0,0 +1,82 @@
+package apikeyrepository
+
+import (
+	"errors"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+	dserrors "github.com/portainer/portainer/api/dataservices/errors"
+)
+
+// BucketName represents the name of the bucket where this service stores data.
+const BucketName = "api_key"
+
+// Service represents a service for managing api-key data.
+type Service struct {
+	dataservices.BaseDataService[portainer.APIKey, portainer.APIKeyID]
+}
+
+// NewService creates a new instance of a service.
+func NewService(connection portainer.Connection) (*Service, error) {
+	if err := connection.SetServiceName(BucketName); err != nil {
+		return nil, err
+	}
+
+	return &Service{
+		BaseDataService: dataservices.BaseDataService[portainer.APIKey, portainer.APIKeyID]{
+			Bucket:     BucketName,
+			Connection: connection,
+		},
+	}, nil
+}
+
+// GetAPIKeysByUserID returns a slice containing all the APIKeys a user has access to.
+func (service *Service) GetAPIKeysByUserID(userID portainer.UserID) ([]portainer.APIKey, error) {
+	result := make([]portainer.APIKey, 0)
+
+	err := service.Connection.GetAll(
+		BucketName,
+		&portainer.APIKey{},
+		dataservices.FilterFn(&result, func(record portainer.APIKey) bool {
+			return record.UserID == userID
+		}),
+	)
+
+	return result, err
+}
+
+// GetAPIKeyByDigest returns the API key for the associated digest.
+// Note: there is a 1-to-1 mapping of api-key and digest
+func (service *Service) GetAPIKeyByDigest(digest string) (*portainer.APIKey, error) {
+	var found portainer.APIKey
+
+	err := service.Connection.GetAll(
+		BucketName,
+		&portainer.APIKey{},
+		dataservices.FirstFn(&found, func(key portainer.APIKey) bool {
+			return key.Digest == digest
+		}),
+	)
+
+	if errors.Is(err, dataservices.ErrStop) {
+		return &found, nil
+	}
+
+	if err == nil {
+		return nil, dserrors.ErrObjectNotFound
+	}
+
+	return nil, err
+}
+
+// Create creates a new APIKey object.
+func (service *Service) Create(record *portainer.APIKey) error {
+	return service.Connection.CreateObject(
+		BucketName,
+		func(id uint64) (int, any) {
+			record.ID = portainer.APIKeyID(id)
+
+			return int(record.ID), record
+		},
+	)
+}

api/dataservices/base.go

@@ -0,0 +1,81 @@
+package dataservices
+
+import (
+	portainer "github.com/portainer/portainer/api"
+
+	"golang.org/x/exp/constraints"
+)
+
+type BaseCRUD[T any, I constraints.Integer] interface {
+	Create(element *T) error
+	Read(ID I) (*T, error)
+	Exists(ID I) (bool, error)
+	ReadAll(predicates ...func(T) bool) ([]T, error)
+	Update(ID I, element *T) error
+	Delete(ID I) error
+}
+
+type BaseDataService[T any, I constraints.Integer] struct {
+	Bucket     string
+	Connection portainer.Connection
+}
+
+func (s *BaseDataService[T, I]) BucketName() string {
+	return s.Bucket
+}
+
+func (service *BaseDataService[T, I]) Tx(tx portainer.Transaction) BaseDataServiceTx[T, I] {
+	return BaseDataServiceTx[T, I]{
+		Bucket:     service.Bucket,
+		Connection: service.Connection,
+		Tx:         tx,
+	}
+}
+
+func (service BaseDataService[T, I]) Read(ID I) (*T, error) {
+	var element *T
+
+	return element, service.Connection.ViewTx(func(tx portainer.Transaction) error {
+		var err error
+		element, err = service.Tx(tx).Read(ID)
+
+		return err
+	})
+}
+
+func (service BaseDataService[T, I]) Exists(ID I) (bool, error) {
+	var exists bool
+
+	err := service.Connection.ViewTx(func(tx portainer.Transaction) error {
+		var err error
+		exists, err = service.Tx(tx).Exists(ID)
+
+		return err
+	})
+
+	return exists, err
+}
+
+// ReadAll retrieves all the elements that satisfy all the provided predicates.
+func (service BaseDataService[T, I]) ReadAll(predicates ...func(T) bool) ([]T, error) {
+	var collection = make([]T, 0)
+
+	return collection, service.Connection.ViewTx(func(tx portainer.Transaction) error {
+		var err error
+		collection, err = service.Tx(tx).ReadAll(predicates...)
+
+		return err
+	})
+}
+
+func (service BaseDataService[T, I]) Update(ID I, element *T) error {
+	return service.Connection.UpdateTx(func(tx portainer.Transaction) error {
+		return service.Tx(tx).Update(ID, element)
+	})
+}
+
+func (service BaseDataService[T, I]) Delete(ID I) error {
+	return service.Connection.UpdateTx(func(tx portainer.Transaction) error {
+		return service.Tx(tx).Delete(ID)
+	})
+}

api/dataservices/base_test.go

@@ -0,0 +1,92 @@
+package dataservices
+
+import (
+	"strconv"
+	"testing"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/slicesx"
+
+	"github.com/stretchr/testify/require"
+)
+
+type testObject struct {
+	ID    int
+	Value int
+}
+
+type mockConnection struct {
+	store map[int]testObject
+
+	portainer.Connection
+}
+
+func (m mockConnection) UpdateObject(bucket string, key []byte, value any) error {
+	obj := value.(*testObject)
+
+	m.store[obj.ID] = *obj
+
+	return nil
+}
+
+func (m mockConnection) GetAll(bucketName string, obj any, appendFn func(o any) (any, error)) error {
+	for _, v := range m.store {
+		if _, err := appendFn(&v); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (m mockConnection) UpdateTx(fn func(portainer.Transaction) error) error {
+	return fn(m)
+}
+
+func (m mockConnection) ViewTx(fn func(portainer.Transaction) error) error {
+	return fn(m)
+}
+
+func (m mockConnection) ConvertToKey(v int) []byte {
+	return []byte(strconv.Itoa(v))
+}
+func TestReadAll(t *testing.T) {
+	t.Parallel()
+	service := BaseDataService[testObject, int]{
+		Bucket:     "testBucket",
+		Connection: mockConnection{store: make(map[int]testObject)},
+	}
+
+	data := []testObject{
+		{ID: 1, Value: 1},
+		{ID: 2, Value: 2},
+		{ID: 3, Value: 3},
+		{ID: 4, Value: 4},
+		{ID: 5, Value: 5},
+	}
+
+	for _, item := range data {
+		err := service.Update(item.ID, &item)
+		require.NoError(t, err)
+	}
+
+	// ReadAll without predicates
+	result, err := service.ReadAll()
+	require.NoError(t, err)
+
+	expected := append([]testObject{}, data...)
+
+	require.ElementsMatch(t, expected, result)
+
+	// ReadAll with predicates
+	hasLowID := func(obj testObject) bool { return obj.ID < 3 }
+	isEven := func(obj testObject) bool { return obj.Value%2 == 0 }
+
+	result, err = service.ReadAll(hasLowID, isEven)
+	require.NoError(t, err)
+
+	expected = slicesx.Filter(expected, hasLowID)
+	expected = slicesx.Filter(expected, isEven)
+
+	require.ElementsMatch(t, expected, result)
+}

api/dataservices/base_tx.go

@@ -0,0 +1,84 @@
+package dataservices
+
+import (
+	portainer "github.com/portainer/portainer/api"
+
+	"golang.org/x/exp/constraints"
+)
+
+type BaseDataServiceTx[T any, I constraints.Integer] struct {
+	Bucket     string
+	Connection portainer.Connection
+	Tx         portainer.Transaction
+}
+
+func (service BaseDataServiceTx[T, I]) BucketName() string {
+	return service.Bucket
+}
+
+func (service BaseDataServiceTx[T, I]) Read(ID I) (*T, error) {
+	var element T
+	identifier := service.Connection.ConvertToKey(int(ID))
+
+	err := service.Tx.GetObject(service.Bucket, identifier, &element)
+	if err != nil {
+		return nil, err
+	}
+
+	return &element, nil
+}
+
+func (service BaseDataServiceTx[T, I]) Exists(ID I) (bool, error) {
+	identifier := service.Connection.ConvertToKey(int(ID))
+
+	return service.Tx.KeyExists(service.Bucket, identifier)
+}
+
+// ReadAll retrieves all the elements that satisfy all the provided predicates.
+func (service BaseDataServiceTx[T, I]) ReadAll(predicates ...func(T) bool) ([]T, error) {
+	var collection = make([]T, 0)
+
+	if len(predicates) == 0 {
+		return collection, service.Tx.GetAll(
+			service.Bucket,
+			new(T),
+			AppendFn(&collection),
+		)
+	}
+
+	filterFn := func(element T) bool {
+		for _, p := range predicates {
+			if !p(element) {
+				return false
+			}
+		}
+
+		return true
+	}
+
+	return collection, service.Tx.GetAll(
+		service.Bucket,
+		new(T),
+		FilterFn(&collection, filterFn),
+	)
+}
+
+func (service BaseDataServiceTx[T, I]) Update(ID I, element *T) error {
+	identifier := service.Connection.ConvertToKey(int(ID))
+	return service.Tx.UpdateObject(service.Bucket, identifier, element)
+}
+
+func (service BaseDataServiceTx[T, I]) Delete(ID I) error {
+	identifier := service.Connection.ConvertToKey(int(ID))
+	return service.Tx.DeleteObject(service.Bucket, identifier)
+}
+
+func Read[T any](tx portainer.Transaction, bucket string, key []byte) (*T, error) {
+	var element T
+
+	if err := tx.GetObject(bucket, key, &element); err != nil {
+		return nil, err
+	}
+
+	return &element, nil
+}

api/dataservices/customtemplate/customtemplate.go

@@ -0,0 +1,39 @@
+package customtemplate
+
+import (
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+// BucketName represents the name of the bucket where this service stores data.
+const BucketName = "customtemplates"
+
+// Service represents a service for managing custom template data.
+type Service struct {
+	dataservices.BaseDataService[portainer.CustomTemplate, portainer.CustomTemplateID]
+}
+
+// NewService creates a new instance of a service.
+func NewService(connection portainer.Connection) (*Service, error) {
+	err := connection.SetServiceName(BucketName)
+	if err != nil {
+		return nil, err
+	}
+
+	return &Service{
+		BaseDataService: dataservices.BaseDataService[portainer.CustomTemplate, portainer.CustomTemplateID]{
+			Bucket:     BucketName,
+			Connection: connection,
+		},
+	}, nil
+}
+
+func (service *Service) GetNextIdentifier() int {
+	return service.Connection.GetNextIdentifier(BucketName)
+}
+
+func (service *Service) Create(customTemplate *portainer.CustomTemplate) error {
+	return service.Connection.UpdateTx(func(tx portainer.Transaction) error {
+		return service.Tx(tx).Create(customTemplate)
+	})
+}

api/dataservices/customtemplate/customtemplate_test.go

@@ -0,0 +1,20 @@
+package customtemplate_test
+
+import (
+	"testing"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/datastore"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCustomTemplateCreate(t *testing.T) {
+	t.Parallel()
+	_, ds := datastore.MustNewTestStore(t, false, false)
+	require.NotNil(t, ds)
+
+	require.NoError(t, ds.CustomTemplate().Create(&portainer.CustomTemplate{ID: 1}))
+	e, err := ds.CustomTemplate().Read(1)
+	require.NoError(t, err)
+	require.Equal(t, portainer.CustomTemplateID(1), e.ID)
+}

api/dataservices/customtemplate/tx.go

@@ -0,0 +1,31 @@
+package customtemplate
+
+import (
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+// Service represents a service for managing custom template data.
+type ServiceTx struct {
+	dataservices.BaseDataServiceTx[portainer.CustomTemplate, portainer.CustomTemplateID]
+}
+
+func (service *Service) Tx(tx portainer.Transaction) ServiceTx {
+	return ServiceTx{
+		BaseDataServiceTx: dataservices.BaseDataServiceTx[portainer.CustomTemplate, portainer.CustomTemplateID]{
+			Bucket:     BucketName,
+			Connection: service.Connection,
+			Tx:         tx,
+		},
+	}
+}
+
+func (service ServiceTx) GetNextIdentifier() int {
+	return service.Tx.GetNextIdentifier(BucketName)
+}
+
+// CreateCustomTemplate uses the existing id and saves it.
+// TODO: where does the ID come from, and is it safe?
+func (service ServiceTx) Create(customTemplate *portainer.CustomTemplate) error {
+	return service.Tx.CreateObjectWithId(BucketName, int(customTemplate.ID), customTemplate)
+}

api/dataservices/customtemplate/tx_test.go

@@ -0,0 +1,29 @@
+package customtemplate_test
+
+import (
+	"testing"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+	"github.com/portainer/portainer/api/datastore"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCustomTemplateCreateTx(t *testing.T) {
+	t.Parallel()
+	_, ds := datastore.MustNewTestStore(t, false, false)
+	require.NotNil(t, ds)
+
+	require.NoError(t, ds.UpdateTx(func(tx dataservices.DataStoreTx) error {
+		return tx.CustomTemplate().Create(&portainer.CustomTemplate{ID: 1})
+	}))
+
+	var template *portainer.CustomTemplate
+	require.NoError(t, ds.ViewTx(func(tx dataservices.DataStoreTx) error {
+		var err error
+		template, err = tx.CustomTemplate().Read(1)
+		return err
+	}))
+
+	require.Equal(t, portainer.CustomTemplateID(1), template.ID)
+}

api/dataservices/dockerhub/dockerhub.go

@@ -0,0 +1,49 @@
+package dockerhub
+
+import (
+	portainer "github.com/portainer/portainer/api"
+)
+
+const (
+	// BucketName represents the name of the bucket where this service stores data.
+	BucketName   = "dockerhub"
+	dockerHubKey = "DOCKERHUB"
+)
+
+// Service represents a service for managing Dockerhub data.
+type Service struct {
+	connection portainer.Connection
+}
+
+func (service *Service) BucketName() string {
+	return BucketName
+}
+
+// NewService creates a new instance of a service.
+func NewService(connection portainer.Connection) (*Service, error) {
+	err := connection.SetServiceName(BucketName)
+	if err != nil {
+		return nil, err
+	}
+
+	return &Service{
+		connection: connection,
+	}, nil
+}
+
+// DockerHub returns the DockerHub object.
+func (service *Service) DockerHub() (*portainer.DockerHub, error) {
+	var dockerhub portainer.DockerHub
+
+	err := service.connection.GetObject(BucketName, []byte(dockerHubKey), &dockerhub)
+	if err != nil {
+		return nil, err
+	}
+
+	return &dockerhub, nil
+}
+
+// UpdateDockerHub updates a DockerHub object.
+func (service *Service) UpdateDockerHub(dockerhub *portainer.DockerHub) error {
+	return service.connection.UpdateObject(BucketName, []byte(dockerHubKey), dockerhub)
+}

api/dataservices/edgegroup/edgegroup.go

@@ -0,0 +1,60 @@
+package edgegroup
+
+import (
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+// BucketName represents the name of the bucket where this service stores data.
+const BucketName = "edgegroups"
+
+// Service represents a service for managing Edge group data.
+type Service struct {
+	dataservices.BaseDataService[portainer.EdgeGroup, portainer.EdgeGroupID]
+}
+
+func (service *Service) BucketName() string {
+	return BucketName
+}
+
+// NewService creates a new instance of a service.
+func NewService(connection portainer.Connection) (*Service, error) {
+	err := connection.SetServiceName(BucketName)
+	if err != nil {
+		return nil, err
+	}
+
+	return &Service{
+		BaseDataService: dataservices.BaseDataService[portainer.EdgeGroup, portainer.EdgeGroupID]{
+			Bucket:     BucketName,
+			Connection: connection,
+		},
+	}, nil
+}
+
+func (service *Service) Tx(tx portainer.Transaction) ServiceTx {
+	return ServiceTx{
+		BaseDataServiceTx: dataservices.BaseDataServiceTx[portainer.EdgeGroup, portainer.EdgeGroupID]{
+			Bucket:     BucketName,
+			Connection: service.Connection,
+			Tx:         tx,
+		},
+	}
+}
+
+// Deprecated: UpdateEdgeGroupFunc updates an edge group inside a transaction avoiding data races.
+func (service *Service) UpdateEdgeGroupFunc(ID portainer.EdgeGroupID, updateFunc func(edgeGroup *portainer.EdgeGroup)) error {
+	id := service.Connection.ConvertToKey(int(ID))
+	edgeGroup := &portainer.EdgeGroup{}
+
+	return service.Connection.UpdateObjectFunc(BucketName, id, edgeGroup, func() {
+		updateFunc(edgeGroup)
+	})
+}
+
+// CreateEdgeGroup assign an ID to a new Edge group and saves it.
+func (service *Service) Create(group *portainer.EdgeGroup) error {
+	return service.Connection.UpdateTx(func(tx portainer.Transaction) error {
+		return service.Tx(tx).Create(group)
+	})
+}

api/dataservices/edgegroup/tx.go

@@ -0,0 +1,45 @@
+package edgegroup
+
+import (
+	"errors"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+type ServiceTx struct {
+	dataservices.BaseDataServiceTx[portainer.EdgeGroup, portainer.EdgeGroupID]
+}
+
+// UpdateEdgeGroupFunc is a no-op inside a transaction.
+func (service ServiceTx) UpdateEdgeGroupFunc(ID portainer.EdgeGroupID, updateFunc func(edgeGroup *portainer.EdgeGroup)) error {
+	return errors.New("cannot be called inside a transaction")
+}
+
+func (service ServiceTx) Create(group *portainer.EdgeGroup) error {
+	es := group.Endpoints
+	group.Endpoints = nil // Clear deprecated field
+
+	err := service.Tx.CreateObject(
+		BucketName,
+		func(id uint64) (int, any) {
+			group.ID = portainer.EdgeGroupID(id)
+			return int(group.ID), group
+		},
+	)
+
+	group.Endpoints = es // Restore endpoints after create
+
+	return err
+}
+
+func (service ServiceTx) Update(ID portainer.EdgeGroupID, group *portainer.EdgeGroup) error {
+	es := group.Endpoints
+	group.Endpoints = nil // Clear deprecated field
+
+	err := service.BaseDataServiceTx.Update(ID, group)
+
+	group.Endpoints = es // Restore endpoints after update
+
+	return err
+}

api/dataservices/edgejob/edgejob.go

@@ -0,0 +1,70 @@
+package edgejob
+
+import (
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+// BucketName represents the name of the bucket where this service stores data.
+const BucketName = "edgejobs"
+
+// Service represents a service for managing edge jobs data.
+type Service struct {
+	dataservices.BaseDataService[portainer.EdgeJob, portainer.EdgeJobID]
+}
+
+// NewService creates a new instance of a service.
+func NewService(connection portainer.Connection) (*Service, error) {
+	err := connection.SetServiceName(BucketName)
+	if err != nil {
+		return nil, err
+	}
+
+	return &Service{
+		BaseDataService: dataservices.BaseDataService[portainer.EdgeJob, portainer.EdgeJobID]{
+			Bucket:     BucketName,
+			Connection: connection,
+		},
+	}, nil
+}
+
+func (service *Service) Tx(tx portainer.Transaction) ServiceTx {
+	return ServiceTx{
+		BaseDataServiceTx: dataservices.BaseDataServiceTx[portainer.EdgeJob, portainer.EdgeJobID]{
+			Bucket:     BucketName,
+			Connection: service.Connection,
+			Tx:         tx,
+		},
+	}
+}
+
+// Create creates a new EdgeJob
+func (service *Service) Create(edgeJob *portainer.EdgeJob) error {
+	return service.CreateWithID(portainer.EdgeJobID(service.GetNextIdentifier()), edgeJob)
+}
+
+// CreateWithID creates a new EdgeJob
+func (service *Service) CreateWithID(ID portainer.EdgeJobID, edgeJob *portainer.EdgeJob) error {
+	edgeJob.ID = ID
+
+	return service.Connection.CreateObjectWithId(
+		BucketName,
+		int(edgeJob.ID),
+		edgeJob,
+	)
+}
+
+// UpdateEdgeJobFunc updates an edge job inside a transaction avoiding data races.
+func (service *Service) UpdateEdgeJobFunc(ID portainer.EdgeJobID, updateFunc func(edgeJob *portainer.EdgeJob)) error {
+	id := service.Connection.ConvertToKey(int(ID))
+	edgeJob := &portainer.EdgeJob{}
+
+	return service.Connection.UpdateObjectFunc(BucketName, id, edgeJob, func() {
+		updateFunc(edgeJob)
+	})
+}
+
+// GetNextIdentifier returns the next identifier for an environment(endpoint).
+func (service *Service) GetNextIdentifier() int {
+	return service.Connection.GetNextIdentifier(BucketName)
+}

api/dataservices/edgejob/tx.go

@@ -0,0 +1,34 @@
+package edgejob
+
+import (
+	"errors"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+type ServiceTx struct {
+	dataservices.BaseDataServiceTx[portainer.EdgeJob, portainer.EdgeJobID]
+}
+
+// Create creates a new EdgeJob
+func (service ServiceTx) Create(edgeJob *portainer.EdgeJob) error {
+	return service.CreateWithID(portainer.EdgeJobID(service.GetNextIdentifier()), edgeJob)
+}
+
+// CreateWithID creates a new EdgeJob
+func (service ServiceTx) CreateWithID(ID portainer.EdgeJobID, edgeJob *portainer.EdgeJob) error {
+	edgeJob.ID = ID
+
+	return service.Tx.CreateObjectWithId(BucketName, int(edgeJob.ID), edgeJob)
+}
+
+// UpdateEdgeJobFunc is a no-op inside a transaction.
+func (service ServiceTx) UpdateEdgeJobFunc(ID portainer.EdgeJobID, updateFunc func(edgeJob *portainer.EdgeJob)) error {
+	return errors.New("cannot be called inside a transaction")
+}
+
+// GetNextIdentifier returns the next identifier for an environment(endpoint).
+func (service ServiceTx) GetNextIdentifier() int {
+	return service.Tx.GetNextIdentifier(BucketName)
+}

api/dataservices/edgestack/edgestack.go

@@ -0,0 +1,176 @@
+package edgestack
+
+import (
+	"sync"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+// BucketName represents the name of the bucket where this service stores data.
+const BucketName = "edge_stack"
+
+// Service represents a service for managing Edge stack data.
+type Service struct {
+	connection          portainer.Connection
+	idxVersion          map[portainer.EdgeStackID]int
+	mu                  sync.RWMutex
+	cacheInvalidationFn func(portainer.Transaction, portainer.EdgeStackID)
+}
+
+func (service *Service) BucketName() string {
+	return BucketName
+}
+
+// NewService creates a new instance of a service.
+func NewService(connection portainer.Connection, cacheInvalidationFn func(portainer.Transaction, portainer.EdgeStackID)) (*Service, error) {
+	err := connection.SetServiceName(BucketName)
+	if err != nil {
+		return nil, err
+	}
+
+	s := &Service{
+		connection:          connection,
+		idxVersion:          make(map[portainer.EdgeStackID]int),
+		cacheInvalidationFn: cacheInvalidationFn,
+	}
+
+	if s.cacheInvalidationFn == nil {
+		s.cacheInvalidationFn = func(portainer.Transaction, portainer.EdgeStackID) {}
+	}
+
+	es, err := s.EdgeStacks()
+	if err != nil {
+		return nil, err
+	}
+
+	for _, e := range es {
+		s.idxVersion[e.ID] = e.Version
+	}
+
+	return s, nil
+}
+
+func (service *Service) Tx(tx portainer.Transaction) ServiceTx {
+	return ServiceTx{
+		service: service,
+		tx:      tx,
+	}
+}
+
+// EdgeStacks returns an array containing all edge stacks
+func (service *Service) EdgeStacks() ([]portainer.EdgeStack, error) {
+	var stacks = make([]portainer.EdgeStack, 0)
+
+	return stacks, service.connection.GetAll(
+		BucketName,
+		&portainer.EdgeStack{},
+		dataservices.AppendFn(&stacks),
+	)
+}
+
+// EdgeStack returns an Edge stack by ID.
+func (service *Service) EdgeStack(ID portainer.EdgeStackID) (*portainer.EdgeStack, error) {
+	var stack portainer.EdgeStack
+	identifier := service.connection.ConvertToKey(int(ID))
+
+	err := service.connection.GetObject(BucketName, identifier, &stack)
+	if err != nil {
+		return nil, err
+	}
+
+	return &stack, nil
+}
+
+// EdgeStackVersion returns the version of the given edge stack ID directly from an in-memory index
+func (service *Service) EdgeStackVersion(ID portainer.EdgeStackID) (int, bool) {
+	service.mu.RLock()
+	v, ok := service.idxVersion[ID]
+	service.mu.RUnlock()
+
+	return v, ok
+}
+
+// CreateEdgeStack saves an Edge stack object to db.
+func (service *Service) Create(id portainer.EdgeStackID, edgeStack *portainer.EdgeStack) error {
+	edgeStack.ID = id
+
+	err := service.connection.CreateObjectWithId(
+		BucketName,
+		int(edgeStack.ID),
+		edgeStack,
+	)
+	if err != nil {
+		return err
+	}
+
+	service.mu.Lock()
+	service.idxVersion[id] = edgeStack.Version
+	service.cacheInvalidationFn(service.connection, id)
+	service.mu.Unlock()
+
+	return nil
+}
+
+// Deprecated: Use UpdateEdgeStackFunc instead.
+func (service *Service) UpdateEdgeStack(ID portainer.EdgeStackID, edgeStack *portainer.EdgeStack) error {
+	service.mu.Lock()
+	defer service.mu.Unlock()
+
+	identifier := service.connection.ConvertToKey(int(ID))
+
+	err := service.connection.UpdateObject(BucketName, identifier, edgeStack)
+	if err != nil {
+		return err
+	}
+
+	service.idxVersion[ID] = edgeStack.Version
+	service.cacheInvalidationFn(service.connection, ID)
+
+	return nil
+}
+
+// UpdateEdgeStackFunc updates an Edge stack inside a transaction avoiding data races.
+func (service *Service) UpdateEdgeStackFunc(ID portainer.EdgeStackID, updateFunc func(edgeStack *portainer.EdgeStack)) error {
+	id := service.connection.ConvertToKey(int(ID))
+	edgeStack := &portainer.EdgeStack{}
+
+	service.mu.Lock()
+	defer service.mu.Unlock()
+
+	return service.connection.UpdateObjectFunc(BucketName, id, edgeStack, func() {
+		updateFunc(edgeStack)
+
+		service.idxVersion[ID] = edgeStack.Version
+		service.cacheInvalidationFn(service.connection, ID)
+	})
+}
+
+// UpdateEdgeStackFuncTx is a helper function used to call UpdateEdgeStackFunc inside a transaction.
+func (service *Service) UpdateEdgeStackFuncTx(tx portainer.Transaction, ID portainer.EdgeStackID, updateFunc func(edgeStack *portainer.EdgeStack)) error {
+	return service.Tx(tx).UpdateEdgeStackFunc(ID, updateFunc)
+}
+
+// DeleteEdgeStack deletes an Edge stack.
+func (service *Service) DeleteEdgeStack(ID portainer.EdgeStackID) error {
+	service.mu.Lock()
+	defer service.mu.Unlock()
+
+	identifier := service.connection.ConvertToKey(int(ID))
+
+	err := service.connection.DeleteObject(BucketName, identifier)
+	if err != nil {
+		return err
+	}
+
+	delete(service.idxVersion, ID)
+
+	service.cacheInvalidationFn(service.connection, ID)
+
+	return nil
+}
+
+// GetNextIdentifier returns the next identifier for an environment(endpoint).
+func (service *Service) GetNextIdentifier() int {
+	return service.connection.GetNextIdentifier(BucketName)
+}

api/dataservices/edgestack/edgestack_test.go

@@ -0,0 +1,52 @@
+package edgestack
+
+import (
+	"testing"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/database/boltdb"
+	"github.com/portainer/portainer/api/logs"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestUpdate(t *testing.T) {
+	t.Parallel()
+	var conn portainer.Connection = &boltdb.DbConnection{Path: t.TempDir()}
+	err := conn.Open()
+	require.NoError(t, err)
+
+	defer logs.CloseAndLogErr(conn)
+
+	service, err := NewService(conn, func(portainer.Transaction, portainer.EdgeStackID) {})
+	require.NoError(t, err)
+
+	const edgeStackID = 1
+	edgeStack := &portainer.EdgeStack{
+		ID:   edgeStackID,
+		Name: "Test Stack",
+	}
+
+	err = service.Create(edgeStackID, edgeStack)
+	require.NoError(t, err)
+
+	err = service.UpdateEdgeStackFunc(edgeStackID, func(edgeStack *portainer.EdgeStack) {
+		edgeStack.Name = "Updated Stack"
+	})
+	require.NoError(t, err)
+
+	updatedStack, err := service.EdgeStack(edgeStackID)
+	require.NoError(t, err)
+	require.Equal(t, "Updated Stack", updatedStack.Name)
+
+	err = conn.UpdateTx(func(tx portainer.Transaction) error {
+		return service.UpdateEdgeStackFuncTx(tx, edgeStackID, func(edgeStack *portainer.EdgeStack) {
+			edgeStack.Name = "Updated Stack Again"
+		})
+	})
+	require.NoError(t, err)
+
+	updatedStack, err = service.EdgeStack(edgeStackID)
+	require.NoError(t, err)
+	require.Equal(t, "Updated Stack Again", updatedStack.Name)
+}

api/dataservices/edgestack/tx.go

@@ -0,0 +1,121 @@
+package edgestack
+
+import (
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+type ServiceTx struct {
+	service *Service
+	tx      portainer.Transaction
+}
+
+func (service ServiceTx) BucketName() string {
+	return BucketName
+}
+
+// EdgeStacks returns an array containing all edge stacks
+func (service ServiceTx) EdgeStacks() ([]portainer.EdgeStack, error) {
+	var stacks = make([]portainer.EdgeStack, 0)
+
+	err := service.tx.GetAll(
+		BucketName,
+		&portainer.EdgeStack{},
+		dataservices.AppendFn(&stacks),
+	)
+
+	return stacks, err
+}
+
+// EdgeStack returns an Edge stack by ID.
+func (service ServiceTx) EdgeStack(ID portainer.EdgeStackID) (*portainer.EdgeStack, error) {
+	var stack portainer.EdgeStack
+	identifier := service.service.connection.ConvertToKey(int(ID))
+
+	if err := service.tx.GetObject(BucketName, identifier, &stack); err != nil {
+		return nil, err
+	}
+
+	return &stack, nil
+}
+
+// EdgeStackVersion returns the version of the given edge stack ID directly from an in-memory index
+func (service ServiceTx) EdgeStackVersion(ID portainer.EdgeStackID) (int, bool) {
+	service.service.mu.RLock()
+	v, ok := service.service.idxVersion[ID]
+	service.service.mu.RUnlock()
+
+	return v, ok
+}
+
+// CreateEdgeStack saves an Edge stack object to db.
+func (service ServiceTx) Create(id portainer.EdgeStackID, edgeStack *portainer.EdgeStack) error {
+	edgeStack.ID = id
+
+	if err := service.tx.CreateObjectWithId(
+		BucketName,
+		int(edgeStack.ID),
+		edgeStack,
+	); err != nil {
+		return err
+	}
+
+	service.service.mu.Lock()
+	service.service.idxVersion[id] = edgeStack.Version
+	service.service.cacheInvalidationFn(service.tx, id)
+	service.service.mu.Unlock()
+
+	return nil
+}
+
+// UpdateEdgeStack updates an Edge stack.
+func (service ServiceTx) UpdateEdgeStack(ID portainer.EdgeStackID, edgeStack *portainer.EdgeStack) error {
+	service.service.mu.Lock()
+	defer service.service.mu.Unlock()
+
+	identifier := service.service.connection.ConvertToKey(int(ID))
+
+	if err := service.tx.UpdateObject(BucketName, identifier, edgeStack); err != nil {
+		return err
+	}
+
+	service.service.idxVersion[ID] = edgeStack.Version
+	service.service.cacheInvalidationFn(service.tx, ID)
+
+	return nil
+}
+
+// Deprecated: use UpdateEdgeStack inside a transaction instead.
+func (service ServiceTx) UpdateEdgeStackFunc(ID portainer.EdgeStackID, updateFunc func(edgeStack *portainer.EdgeStack)) error {
+	edgeStack, err := service.EdgeStack(ID)
+	if err != nil {
+		return err
+	}
+
+	updateFunc(edgeStack)
+
+	return service.UpdateEdgeStack(ID, edgeStack)
+}
+
+// DeleteEdgeStack deletes an Edge stack.
+func (service ServiceTx) DeleteEdgeStack(ID portainer.EdgeStackID) error {
+	service.service.mu.Lock()
+	defer service.service.mu.Unlock()
+
+	identifier := service.service.connection.ConvertToKey(int(ID))
+
+	if err := service.tx.DeleteObject(BucketName, identifier); err != nil {
+		return err
+	}
+
+	delete(service.service.idxVersion, ID)
+
+	service.service.cacheInvalidationFn(service.tx, ID)
+
+	return nil
+}
+
+// GetNextIdentifier returns the next identifier for an environment(endpoint).
+func (service ServiceTx) GetNextIdentifier() int {
+	return service.tx.GetNextIdentifier(BucketName)
+}

api/dataservices/edgestackstatus/edgestackstatus.go

@@ -0,0 +1,95 @@
+package edgestackstatus
+
+import (
+	"encoding/binary"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+var _ dataservices.EdgeStackStatusService = &Service{}
+
+const BucketName = "edge_stack_status"
+
+type Service struct {
+	conn portainer.Connection
+}
+
+func (service *Service) BucketName() string {
+	return BucketName
+}
+
+func NewService(connection portainer.Connection) (*Service, error) {
+	if err := connection.SetServiceName(BucketName); err != nil {
+		return nil, err
+	}
+
+	return &Service{conn: connection}, nil
+}
+
+func (s *Service) Tx(tx portainer.Transaction) ServiceTx {
+	return ServiceTx{
+		service: s,
+		tx:      tx,
+	}
+}
+
+func (s *Service) Create(edgeStackID portainer.EdgeStackID, endpointID portainer.EndpointID, status *portainer.EdgeStackStatusForEnv) error {
+	return s.conn.UpdateTx(func(tx portainer.Transaction) error {
+		return s.Tx(tx).Create(edgeStackID, endpointID, status)
+	})
+}
+
+func (s *Service) Read(edgeStackID portainer.EdgeStackID, endpointID portainer.EndpointID) (*portainer.EdgeStackStatusForEnv, error) {
+	var element *portainer.EdgeStackStatusForEnv
+
+	return element, s.conn.ViewTx(func(tx portainer.Transaction) error {
+		var err error
+		element, err = s.Tx(tx).Read(edgeStackID, endpointID)
+
+		return err
+	})
+}
+
+func (s *Service) ReadAll(edgeStackID portainer.EdgeStackID) ([]portainer.EdgeStackStatusForEnv, error) {
+	var collection = make([]portainer.EdgeStackStatusForEnv, 0)
+
+	return collection, s.conn.ViewTx(func(tx portainer.Transaction) error {
+		var err error
+		collection, err = s.Tx(tx).ReadAll(edgeStackID)
+
+		return err
+	})
+}
+
+func (s *Service) Update(edgeStackID portainer.EdgeStackID, endpointID portainer.EndpointID, status *portainer.EdgeStackStatusForEnv) error {
+	return s.conn.UpdateTx(func(tx portainer.Transaction) error {
+		return s.Tx(tx).Update(edgeStackID, endpointID, status)
+	})
+}
+
+func (s *Service) Delete(edgeStackID portainer.EdgeStackID, endpointID portainer.EndpointID) error {
+	return s.conn.UpdateTx(func(tx portainer.Transaction) error {
+		return s.Tx(tx).Delete(edgeStackID, endpointID)
+	})
+}
+
+func (s *Service) DeleteAll(edgeStackID portainer.EdgeStackID) error {
+	return s.conn.UpdateTx(func(tx portainer.Transaction) error {
+		return s.Tx(tx).DeleteAll(edgeStackID)
+	})
+}
+
+func (s *Service) Clear(edgeStackID portainer.EdgeStackID, relatedEnvironmentsIDs []portainer.EndpointID) error {
+	return s.conn.UpdateTx(func(tx portainer.Transaction) error {
+		return s.Tx(tx).Clear(edgeStackID, relatedEnvironmentsIDs)
+	})
+}
+
+func (s *Service) key(edgeStackID portainer.EdgeStackID, endpointID portainer.EndpointID) []byte {
+	k := make([]byte, 16)
+	binary.BigEndian.PutUint64(k[:8], uint64(edgeStackID))
+	binary.BigEndian.PutUint64(k[8:], uint64(endpointID))
+
+	return k
+}

api/dataservices/edgestackstatus/tx.go

@@ -0,0 +1,95 @@
+package edgestackstatus
+
+import (
+	"fmt"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+var _ dataservices.EdgeStackStatusService = &Service{}
+
+type ServiceTx struct {
+	service *Service
+	tx      portainer.Transaction
+}
+
+func (service ServiceTx) Create(edgeStackID portainer.EdgeStackID, endpointID portainer.EndpointID, status *portainer.EdgeStackStatusForEnv) error {
+	identifier := service.service.key(edgeStackID, endpointID)
+	return service.tx.CreateObjectWithStringId(BucketName, identifier, status)
+}
+
+func (s ServiceTx) Read(edgeStackID portainer.EdgeStackID, endpointID portainer.EndpointID) (*portainer.EdgeStackStatusForEnv, error) {
+	var status portainer.EdgeStackStatusForEnv
+	identifier := s.service.key(edgeStackID, endpointID)
+
+	if err := s.tx.GetObject(BucketName, identifier, &status); err != nil {
+		return nil, err
+	}
+
+	return &status, nil
+}
+
+func (s ServiceTx) ReadAll(edgeStackID portainer.EdgeStackID) ([]portainer.EdgeStackStatusForEnv, error) {
+	keyPrefix := s.service.conn.ConvertToKey(int(edgeStackID))
+
+	statuses := make([]portainer.EdgeStackStatusForEnv, 0)
+
+	if err := s.tx.GetAllWithKeyPrefix(BucketName, keyPrefix, &portainer.EdgeStackStatusForEnv{}, dataservices.AppendFn(&statuses)); err != nil {
+		return nil, fmt.Errorf("unable to retrieve EdgeStackStatus for EdgeStack %d: %w", edgeStackID, err)
+	}
+
+	return statuses, nil
+}
+
+func (s ServiceTx) Update(edgeStackID portainer.EdgeStackID, endpointID portainer.EndpointID, status *portainer.EdgeStackStatusForEnv) error {
+	identifier := s.service.key(edgeStackID, endpointID)
+	return s.tx.UpdateObject(BucketName, identifier, status)
+}
+
+func (s ServiceTx) Delete(edgeStackID portainer.EdgeStackID, endpointID portainer.EndpointID) error {
+	identifier := s.service.key(edgeStackID, endpointID)
+	return s.tx.DeleteObject(BucketName, identifier)
+}
+
+func (s ServiceTx) DeleteAll(edgeStackID portainer.EdgeStackID) error {
+	keyPrefix := s.service.conn.ConvertToKey(int(edgeStackID))
+
+	statuses := make([]portainer.EdgeStackStatusForEnv, 0)
+
+	if err := s.tx.GetAllWithKeyPrefix(BucketName, keyPrefix, &portainer.EdgeStackStatusForEnv{}, dataservices.AppendFn(&statuses)); err != nil {
+		return fmt.Errorf("unable to retrieve EdgeStackStatus for EdgeStack %d: %w", edgeStackID, err)
+	}
+
+	for _, status := range statuses {
+		if err := s.tx.DeleteObject(BucketName, s.service.key(edgeStackID, status.EndpointID)); err != nil {
+			return fmt.Errorf("unable to delete EdgeStackStatus for EdgeStack %d and Endpoint %d: %w", edgeStackID, status.EndpointID, err)
+		}
+	}
+
+	return nil
+}
+
+func (s ServiceTx) Clear(edgeStackID portainer.EdgeStackID, relatedEnvironmentsIDs []portainer.EndpointID) error {
+	for _, envID := range relatedEnvironmentsIDs {
+		existingStatus, err := s.Read(edgeStackID, envID)
+		if err != nil && !dataservices.IsErrObjectNotFound(err) {
+			return fmt.Errorf("unable to retrieve status for environment %d: %w", envID, err)
+		}
+
+		var deploymentInfo portainer.StackDeploymentInfo
+		if existingStatus != nil {
+			deploymentInfo = existingStatus.DeploymentInfo
+		}
+
+		if err := s.Update(edgeStackID, envID, &portainer.EdgeStackStatusForEnv{
+			EndpointID:     envID,
+			Status:         []portainer.EdgeStackDeploymentStatus{},
+			DeploymentInfo: deploymentInfo,
+		}); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}

api/dataservices/endpoint/endpoint.go

@@ -0,0 +1,194 @@
+package endpoint
+
+import (
+	"sync"
+	"time"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+
+	"github.com/rs/zerolog/log"
+)
+
+// BucketName represents the name of the bucket where this service stores data.
+const BucketName = "endpoints"
+
+// Service represents a service for managing environment(endpoint) data.
+type Service struct {
+	connection portainer.Connection
+	mu         sync.RWMutex
+	idxEdgeID  map[string]portainer.EndpointID
+	heartbeats sync.Map
+}
+
+func (service *Service) BucketName() string {
+	return BucketName
+}
+
+// NewService creates a new instance of a service.
+func NewService(connection portainer.Connection) (*Service, error) {
+	err := connection.SetServiceName(BucketName)
+	if err != nil {
+		return nil, err
+	}
+
+	s := &Service{
+		connection: connection,
+		idxEdgeID:  make(map[string]portainer.EndpointID),
+	}
+
+	es, err := s.endpoints()
+	if err != nil {
+		return nil, err
+	}
+
+	for _, e := range es {
+		if len(e.EdgeID) > 0 {
+			s.idxEdgeID[e.EdgeID] = e.ID
+		}
+
+		s.heartbeats.Store(e.ID, e.LastCheckInDate)
+	}
+
+	return s, nil
+}
+
+func (service *Service) Tx(tx portainer.Transaction) ServiceTx {
+	return ServiceTx{
+		service: service,
+		tx:      tx,
+	}
+}
+
+// Endpoint returns an environment(endpoint) by ID.
+func (service *Service) Endpoint(ID portainer.EndpointID) (*portainer.Endpoint, error) {
+	var endpoint *portainer.Endpoint
+	var err error
+
+	err = service.connection.ViewTx(func(tx portainer.Transaction) error {
+		endpoint, err = service.Tx(tx).Endpoint(ID)
+		return err
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	endpoint.LastCheckInDate, _ = service.Heartbeat(ID)
+
+	return endpoint, nil
+}
+
+// UpdateEndpoint updates an environment(endpoint).
+func (service *Service) UpdateEndpoint(ID portainer.EndpointID, endpoint *portainer.Endpoint) error {
+	return service.connection.UpdateTx(func(tx portainer.Transaction) error {
+		return service.Tx(tx).UpdateEndpoint(ID, endpoint)
+	})
+}
+
+// DeleteEndpoint deletes an environment(endpoint).
+func (service *Service) DeleteEndpoint(ID portainer.EndpointID) error {
+	return service.connection.UpdateTx(func(tx portainer.Transaction) error {
+		return service.Tx(tx).DeleteEndpoint(ID)
+	})
+}
+
+func (service *Service) endpoints() ([]portainer.Endpoint, error) {
+	var endpoints []portainer.Endpoint
+	var err error
+
+	err = service.connection.ViewTx(func(tx portainer.Transaction) error {
+		endpoints, err = service.Tx(tx).Endpoints()
+		return err
+	})
+
+	return endpoints, err
+}
+
+// Endpoints return an array containing all the environments(endpoints).
+func (service *Service) Endpoints() ([]portainer.Endpoint, error) {
+	endpoints, err := service.endpoints()
+	if err != nil {
+		return nil, err
+	}
+
+	for i, e := range endpoints {
+		t, _ := service.Heartbeat(e.ID)
+		endpoints[i].LastCheckInDate = t
+	}
+
+	return endpoints, nil
+}
+
+// ReadAll retrieves all the elements that satisfy all the provided predicates.
+func (service *Service) ReadAll(predicates ...func(endpoint portainer.Endpoint) bool) ([]portainer.Endpoint, error) {
+	var endpoints []portainer.Endpoint
+	var err error
+
+	err = service.connection.ViewTx(func(tx portainer.Transaction) error {
+		endpoints, err = service.Tx(tx).ReadAll(predicates...)
+		return err
+	})
+
+	return endpoints, err
+}
+
+// EndpointIDByEdgeID returns the EndpointID from the given EdgeID using an in-memory index
+func (service *Service) EndpointIDByEdgeID(edgeID string) (portainer.EndpointID, bool) {
+	service.mu.RLock()
+	endpointID, ok := service.idxEdgeID[edgeID]
+	service.mu.RUnlock()
+
+	return endpointID, ok
+}
+
+func (service *Service) Heartbeat(endpointID portainer.EndpointID) (int64, bool) {
+	if t, ok := service.heartbeats.Load(endpointID); ok {
+		return t.(int64), true
+	}
+
+	return 0, false
+}
+
+func (service *Service) UpdateHeartbeat(endpointID portainer.EndpointID) {
+	service.heartbeats.Store(endpointID, time.Now().Unix())
+}
+
+// CreateEndpoint assign an ID to a new environment(endpoint) and saves it.
+func (service *Service) Create(endpoint *portainer.Endpoint) error {
+	return service.connection.UpdateTx(func(tx portainer.Transaction) error {
+		return service.Tx(tx).Create(endpoint)
+	})
+}
+
+func (service *Service) EndpointsByTeamID(teamID portainer.TeamID) ([]portainer.Endpoint, error) {
+	var endpoints = make([]portainer.Endpoint, 0)
+
+	return endpoints, service.connection.GetAll(
+		BucketName,
+		&portainer.Endpoint{},
+		dataservices.FilterFn(&endpoints, func(e portainer.Endpoint) bool {
+			for t := range e.TeamAccessPolicies {
+				if t == teamID {
+					return true
+				}
+			}
+
+			return false
+		}),
+	)
+}
+
+// GetNextIdentifier returns the next identifier for an environment(endpoint).
+func (service *Service) GetNextIdentifier() int {
+	var identifier int
+
+	if err := service.connection.UpdateTx(func(tx portainer.Transaction) error {
+		identifier = service.Tx(tx).GetNextIdentifier()
+
+		return nil
+	}); err != nil {
+		log.Error().Err(err).Str("bucket", BucketName).Msg("could not get the next identifier")
+	}
+
+	return identifier
+}

api/dataservices/endpoint/tx.go

@@ -0,0 +1,151 @@
+package endpoint
+
+import (
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+	"github.com/portainer/portainer/api/internal/edge/cache"
+
+	"github.com/rs/zerolog/log"
+)
+
+type ServiceTx struct {
+	service *Service
+	tx      portainer.Transaction
+}
+
+func (service ServiceTx) BucketName() string {
+	return BucketName
+}
+
+// Endpoint returns an environment(endpoint) by ID.
+func (service ServiceTx) Endpoint(ID portainer.EndpointID) (*portainer.Endpoint, error) {
+	var endpoint portainer.Endpoint
+
+	identifier := service.service.connection.ConvertToKey(int(ID))
+
+	if err := service.tx.GetObject(BucketName, identifier, &endpoint); err != nil {
+		return nil, err
+	}
+
+	endpoint.LastCheckInDate, _ = service.service.Heartbeat(ID)
+
+	return &endpoint, nil
+}
+
+// UpdateEndpoint updates an environment(endpoint).
+func (service ServiceTx) UpdateEndpoint(ID portainer.EndpointID, endpoint *portainer.Endpoint) error {
+	identifier := service.service.connection.ConvertToKey(int(ID))
+
+	if err := service.tx.UpdateObject(BucketName, identifier, endpoint); err != nil {
+		return err
+	}
+
+	service.service.mu.Lock()
+	if len(endpoint.EdgeID) > 0 {
+		service.service.idxEdgeID[endpoint.EdgeID] = ID
+	}
+
+	service.service.heartbeats.Store(ID, endpoint.LastCheckInDate)
+	service.service.mu.Unlock()
+
+	cache.Del(endpoint.ID)
+
+	return nil
+}
+
+// DeleteEndpoint deletes an environment(endpoint).
+func (service ServiceTx) DeleteEndpoint(ID portainer.EndpointID) error {
+	identifier := service.service.connection.ConvertToKey(int(ID))
+
+	if err := service.tx.DeleteObject(BucketName, identifier); err != nil {
+		return err
+	}
+
+	service.service.mu.Lock()
+	for edgeID, endpointID := range service.service.idxEdgeID {
+		if endpointID == ID {
+			delete(service.service.idxEdgeID, edgeID)
+
+			break
+		}
+	}
+
+	service.service.heartbeats.Delete(ID)
+	service.service.mu.Unlock()
+
+	cache.Del(ID)
+
+	return nil
+}
+
+// Endpoints return an array containing all the environments(endpoints).
+func (service ServiceTx) Endpoints() ([]portainer.Endpoint, error) {
+	var endpoints = make([]portainer.Endpoint, 0)
+
+	return endpoints, service.tx.GetAll(
+		BucketName,
+		&portainer.Endpoint{},
+		dataservices.AppendFn(&endpoints),
+	)
+}
+
+// ReadAll retrieves all the elements that satisfy all the provided predicates.
+func (service ServiceTx) ReadAll(predicates ...func(endpoint portainer.Endpoint) bool) ([]portainer.Endpoint, error) {
+	return dataservices.BaseDataServiceTx[portainer.Endpoint, portainer.EndpointID]{Bucket: BucketName, Connection: service.service.connection, Tx: service.tx}.ReadAll(predicates...)
+}
+
+func (service ServiceTx) EndpointIDByEdgeID(edgeID string) (portainer.EndpointID, bool) {
+	log.Error().Str("func", "EndpointIDByEdgeID").Msg("cannot be called inside a transaction")
+
+	return 0, false
+}
+
+func (service ServiceTx) Heartbeat(endpointID portainer.EndpointID) (int64, bool) {
+	log.Error().Str("func", "Heartbeat").Msg("cannot be called inside a transaction")
+
+	return 0, false
+}
+
+func (service ServiceTx) UpdateHeartbeat(endpointID portainer.EndpointID) {
+	log.Error().Str("func", "UpdateHeartbeat").Msg("cannot be called inside a transaction")
+}
+
+// CreateEndpoint assign an ID to a new environment(endpoint) and saves it.
+func (service ServiceTx) Create(endpoint *portainer.Endpoint) error {
+	if err := service.tx.CreateObjectWithId(BucketName, int(endpoint.ID), endpoint); err != nil {
+		return err
+	}
+
+	service.service.mu.Lock()
+	if len(endpoint.EdgeID) > 0 {
+		service.service.idxEdgeID[endpoint.EdgeID] = endpoint.ID
+	}
+
+	service.service.heartbeats.Store(endpoint.ID, endpoint.LastCheckInDate)
+	service.service.mu.Unlock()
+
+	return nil
+}
+
+func (service ServiceTx) EndpointsByTeamID(teamID portainer.TeamID) ([]portainer.Endpoint, error) {
+	var endpoints = make([]portainer.Endpoint, 0)
+
+	return endpoints, service.tx.GetAll(
+		BucketName,
+		&portainer.Endpoint{},
+		dataservices.FilterFn(&endpoints, func(e portainer.Endpoint) bool {
+			for t := range e.TeamAccessPolicies {
+				if t == teamID {
+					return true
+				}
+			}
+
+			return false
+		}),
+	)
+}
+
+// GetNextIdentifier returns the next identifier for an environment(endpoint).
+func (service ServiceTx) GetNextIdentifier() int {
+	return service.tx.GetNextIdentifier(BucketName)
+}

api/dataservices/endpointgroup/endpointgroup.go

@@ -0,0 +1,49 @@
+package endpointgroup
+
+import (
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+const BucketName = "endpoint_groups"
+
+// Service represents a service for managing environment(endpoint) data.
+type Service struct {
+	dataservices.BaseDataService[portainer.EndpointGroup, portainer.EndpointGroupID]
+}
+
+// NewService creates a new instance of a service.
+func NewService(connection portainer.Connection) (*Service, error) {
+	err := connection.SetServiceName(BucketName)
+	if err != nil {
+		return nil, err
+	}
+
+	return &Service{
+		BaseDataService: dataservices.BaseDataService[portainer.EndpointGroup, portainer.EndpointGroupID]{
+			Bucket:     BucketName,
+			Connection: connection,
+		},
+	}, nil
+}
+
+func (service *Service) Tx(tx portainer.Transaction) ServiceTx {
+	return ServiceTx{
+		BaseDataServiceTx: dataservices.BaseDataServiceTx[portainer.EndpointGroup, portainer.EndpointGroupID]{
+			Bucket:     BucketName,
+			Connection: service.Connection,
+			Tx:         tx,
+		},
+	}
+}
+
+// CreateEndpointGroup assign an ID to a new environment(endpoint) group and saves it.
+func (service *Service) Create(endpointGroup *portainer.EndpointGroup) error {
+	return service.Connection.CreateObject(
+		BucketName,
+		func(id uint64) (int, any) {
+			endpointGroup.ID = portainer.EndpointGroupID(id)
+			return int(endpointGroup.ID), endpointGroup
+		},
+	)
+}

api/dataservices/endpointgroup/tx.go

@@ -0,0 +1,21 @@
+package endpointgroup
+
+import (
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+type ServiceTx struct {
+	dataservices.BaseDataServiceTx[portainer.EndpointGroup, portainer.EndpointGroupID]
+}
+
+// CreateEndpointGroup assign an ID to a new environment(endpoint) group and saves it.
+func (service ServiceTx) Create(endpointGroup *portainer.EndpointGroup) error {
+	return service.Tx.CreateObject(
+		BucketName,
+		func(id uint64) (int, any) {
+			endpointGroup.ID = portainer.EndpointGroupID(id)
+			return int(endpointGroup.ID), endpointGroup
+		},
+	)
+}

api/dataservices/endpointrelation/endpointrelation.go

@@ -0,0 +1,114 @@
+package endpointrelation
+
+import (
+	"sync"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+	"github.com/portainer/portainer/api/internal/edge/cache"
+)
+
+// BucketName represents the name of the bucket where this service stores data.
+const BucketName = "endpoint_relations"
+
+// Service represents a service for managing environment(endpoint) relation data.
+type Service struct {
+	connection             portainer.Connection
+	updateStackFnTx        func(tx portainer.Transaction, ID portainer.EdgeStackID, updateFunc func(edgeStack *portainer.EdgeStack)) error
+	endpointRelationsCache []portainer.EndpointRelation
+	mu                     sync.Mutex
+}
+
+var _ dataservices.EndpointRelationService = &Service{}
+
+func (service *Service) BucketName() string {
+	return BucketName
+}
+
+func (service *Service) RegisterUpdateStackFunction(
+	updateFuncTx func(portainer.Transaction, portainer.EdgeStackID, func(*portainer.EdgeStack)) error,
+) {
+	service.mu.Lock()
+	defer service.mu.Unlock()
+
+	service.updateStackFnTx = updateFuncTx
+}
+
+// NewService creates a new instance of a service.
+func NewService(connection portainer.Connection) (*Service, error) {
+	if err := connection.SetServiceName(BucketName); err != nil {
+		return nil, err
+	}
+
+	return &Service{
+		connection: connection,
+	}, nil
+}
+
+func (service *Service) Tx(tx portainer.Transaction) ServiceTx {
+	return ServiceTx{
+		service: service,
+		tx:      tx,
+	}
+}
+
+// EndpointRelations returns an array of all EndpointRelations
+func (service *Service) EndpointRelations() ([]portainer.EndpointRelation, error) {
+	var all = make([]portainer.EndpointRelation, 0)
+
+	return all, service.connection.GetAll(
+		BucketName,
+		&portainer.EndpointRelation{},
+		dataservices.AppendFn(&all),
+	)
+}
+
+// EndpointRelation returns a Environment(Endpoint) relation object by EndpointID
+func (service *Service) EndpointRelation(endpointID portainer.EndpointID) (*portainer.EndpointRelation, error) {
+	var endpointRelation portainer.EndpointRelation
+	identifier := service.connection.ConvertToKey(int(endpointID))
+
+	if err := service.connection.GetObject(BucketName, identifier, &endpointRelation); err != nil {
+		return nil, err
+	}
+
+	return &endpointRelation, nil
+}
+
+// CreateEndpointRelation saves endpointRelation
+func (service *Service) Create(endpointRelation *portainer.EndpointRelation) error {
+	err := service.connection.CreateObjectWithId(BucketName, int(endpointRelation.EndpointID), endpointRelation)
+	cache.Del(endpointRelation.EndpointID)
+
+	service.mu.Lock()
+	service.endpointRelationsCache = nil
+	service.mu.Unlock()
+
+	return err
+}
+
+// UpdateEndpointRelation updates an Environment(Endpoint) relation object
+func (service *Service) UpdateEndpointRelation(endpointID portainer.EndpointID, endpointRelation *portainer.EndpointRelation) error {
+	return service.connection.UpdateTx(func(tx portainer.Transaction) error {
+		return service.Tx(tx).UpdateEndpointRelation(endpointID, endpointRelation)
+	})
+}
+
+func (service *Service) AddEndpointRelationsForEdgeStack(endpointIDs []portainer.EndpointID, edgeStack *portainer.EdgeStack) error {
+	return service.connection.UpdateTx(func(tx portainer.Transaction) error {
+		return service.Tx(tx).AddEndpointRelationsForEdgeStack(endpointIDs, edgeStack)
+	})
+}
+
+func (service *Service) RemoveEndpointRelationsForEdgeStack(endpointIDs []portainer.EndpointID, edgeStackID portainer.EdgeStackID) error {
+	return service.connection.UpdateTx(func(tx portainer.Transaction) error {
+		return service.Tx(tx).RemoveEndpointRelationsForEdgeStack(endpointIDs, edgeStackID)
+	})
+}
+
+// DeleteEndpointRelation deletes an Environment(Endpoint) relation object
+func (service *Service) DeleteEndpointRelation(endpointID portainer.EndpointID) error {
+	return service.connection.UpdateTx(func(tx portainer.Transaction) error {
+		return service.Tx(tx).DeleteEndpointRelation(endpointID)
+	})
+}

api/dataservices/endpointrelation/endpointrelation_test.go

@@ -0,0 +1,144 @@
+package endpointrelation
+
+import (
+	"testing"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/database/boltdb"
+	"github.com/portainer/portainer/api/dataservices/edgestack"
+	"github.com/portainer/portainer/api/internal/edge/cache"
+	"github.com/portainer/portainer/api/logs"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestUpdateRelation(t *testing.T) {
+	t.Parallel()
+	const endpointID = 1
+	const edgeStackID1 = 1
+	const edgeStackID2 = 2
+
+	var conn portainer.Connection = &boltdb.DbConnection{Path: t.TempDir()}
+	err := conn.Open()
+	require.NoError(t, err)
+
+	defer logs.CloseAndLogErr(conn)
+
+	service, err := NewService(conn)
+	require.NoError(t, err)
+
+	updateStackFnTxCalled := false
+
+	edgeStacks := make(map[portainer.EdgeStackID]portainer.EdgeStack)
+	edgeStacks[edgeStackID1] = portainer.EdgeStack{ID: edgeStackID1}
+	edgeStacks[edgeStackID2] = portainer.EdgeStack{ID: edgeStackID2}
+
+	service.RegisterUpdateStackFunction(func(tx portainer.Transaction, ID portainer.EdgeStackID, updateFunc func(edgeStack *portainer.EdgeStack)) error {
+		updateStackFnTxCalled = true
+
+		s, ok := edgeStacks[ID]
+		require.True(t, ok)
+
+		updateFunc(&s)
+		edgeStacks[ID] = s
+
+		return nil
+	})
+
+	// Nil relation
+
+	cache.Set(endpointID, []byte("value"))
+
+	err = service.UpdateEndpointRelation(endpointID, nil)
+	_, cacheKeyExists := cache.Get(endpointID)
+	require.NoError(t, err)
+	require.False(t, updateStackFnTxCalled)
+	require.False(t, cacheKeyExists)
+
+	// Add a relation to two edge stacks
+
+	cache.Set(endpointID, []byte("value"))
+
+	err = service.UpdateEndpointRelation(endpointID, &portainer.EndpointRelation{
+		EndpointID: endpointID,
+		EdgeStacks: map[portainer.EdgeStackID]bool{
+			edgeStackID1: true,
+			edgeStackID2: true,
+		},
+	})
+	_, cacheKeyExists = cache.Get(endpointID)
+	require.NoError(t, err)
+	require.True(t, updateStackFnTxCalled)
+	require.False(t, cacheKeyExists)
+	require.Equal(t, 1, edgeStacks[edgeStackID1].NumDeployments)
+	require.Equal(t, 1, edgeStacks[edgeStackID2].NumDeployments)
+
+	// Remove a relation to one edge stack
+
+	updateStackFnTxCalled = false
+	cache.Set(endpointID, []byte("value"))
+
+	err = service.UpdateEndpointRelation(endpointID, &portainer.EndpointRelation{
+		EndpointID: endpointID,
+		EdgeStacks: map[portainer.EdgeStackID]bool{
+			2: true,
+		},
+	})
+	_, cacheKeyExists = cache.Get(endpointID)
+	require.NoError(t, err)
+	require.True(t, updateStackFnTxCalled)
+	require.False(t, cacheKeyExists)
+	require.Equal(t, 0, edgeStacks[edgeStackID1].NumDeployments)
+	require.Equal(t, 1, edgeStacks[edgeStackID2].NumDeployments)
+
+	// Delete the relation
+
+	updateStackFnTxCalled = false
+	cache.Set(endpointID, []byte("value"))
+
+	err = service.DeleteEndpointRelation(endpointID)
+
+	_, cacheKeyExists = cache.Get(endpointID)
+	require.NoError(t, err)
+	require.True(t, updateStackFnTxCalled)
+	require.False(t, cacheKeyExists)
+	require.Equal(t, 0, edgeStacks[edgeStackID1].NumDeployments)
+	require.Equal(t, 0, edgeStacks[edgeStackID2].NumDeployments)
+}
+
+func TestAddEndpointRelationsForEdgeStack(t *testing.T) {
+	t.Parallel()
+	var conn portainer.Connection = &boltdb.DbConnection{Path: t.TempDir()}
+	err := conn.Open()
+	require.NoError(t, err)
+
+	defer logs.CloseAndLogErr(conn)
+
+	service, err := NewService(conn)
+	require.NoError(t, err)
+
+	edgeStackService, err := edgestack.NewService(conn, func(t portainer.Transaction, esi portainer.EdgeStackID) {})
+	require.NoError(t, err)
+
+	service.RegisterUpdateStackFunction(edgeStackService.UpdateEdgeStackFuncTx)
+	require.NoError(t, edgeStackService.Create(1, &portainer.EdgeStack{}))
+	require.NoError(t, service.Create(&portainer.EndpointRelation{EndpointID: 1, EdgeStacks: map[portainer.EdgeStackID]bool{}}))
+	require.NoError(t, service.AddEndpointRelationsForEdgeStack([]portainer.EndpointID{1}, &portainer.EdgeStack{ID: 1}))
+}
+
+func TestEndpointRelations(t *testing.T) {
+	t.Parallel()
+	var conn portainer.Connection = &boltdb.DbConnection{Path: t.TempDir()}
+	err := conn.Open()
+	require.NoError(t, err)
+
+	defer logs.CloseAndLogErr(conn)
+
+	service, err := NewService(conn)
+	require.NoError(t, err)
+
+	require.NoError(t, service.Create(&portainer.EndpointRelation{EndpointID: 1}))
+	rels, err := service.EndpointRelations()
+	require.NoError(t, err)
+	require.Len(t, rels, 1)
+}

api/dataservices/endpointrelation/tx.go

@@ -0,0 +1,238 @@
+package endpointrelation
+
+import (
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+	"github.com/portainer/portainer/api/internal/edge/cache"
+
+	"github.com/rs/zerolog/log"
+)
+
+type ServiceTx struct {
+	service *Service
+	tx      portainer.Transaction
+}
+
+var _ dataservices.EndpointRelationService = &ServiceTx{}
+
+func (service ServiceTx) BucketName() string {
+	return BucketName
+}
+
+// EndpointRelations returns an array of all EndpointRelations
+func (service ServiceTx) EndpointRelations() ([]portainer.EndpointRelation, error) {
+	var all = make([]portainer.EndpointRelation, 0)
+
+	return all, service.tx.GetAll(
+		BucketName,
+		&portainer.EndpointRelation{},
+		dataservices.AppendFn(&all),
+	)
+}
+
+// EndpointRelation returns an Environment(Endpoint) relation object by EndpointID
+func (service ServiceTx) EndpointRelation(endpointID portainer.EndpointID) (*portainer.EndpointRelation, error) {
+	var endpointRelation portainer.EndpointRelation
+	identifier := service.service.connection.ConvertToKey(int(endpointID))
+
+	if err := service.tx.GetObject(BucketName, identifier, &endpointRelation); err != nil {
+		return nil, err
+	}
+
+	return &endpointRelation, nil
+}
+
+// CreateEndpointRelation saves endpointRelation
+func (service ServiceTx) Create(endpointRelation *portainer.EndpointRelation) error {
+	err := service.tx.CreateObjectWithId(BucketName, int(endpointRelation.EndpointID), endpointRelation)
+	cache.Del(endpointRelation.EndpointID)
+
+	service.service.mu.Lock()
+	service.service.endpointRelationsCache = nil
+	service.service.mu.Unlock()
+
+	return err
+}
+
+// UpdateEndpointRelation updates an Environment(Endpoint) relation object
+func (service ServiceTx) UpdateEndpointRelation(endpointID portainer.EndpointID, endpointRelation *portainer.EndpointRelation) error {
+	previousRelationState, _ := service.EndpointRelation(endpointID)
+
+	identifier := service.service.connection.ConvertToKey(int(endpointID))
+	err := service.tx.UpdateObject(BucketName, identifier, endpointRelation)
+	cache.Del(endpointID)
+	if err != nil {
+		return err
+	}
+
+	updatedRelationState, _ := service.EndpointRelation(endpointID)
+
+	service.service.mu.Lock()
+	service.service.endpointRelationsCache = nil
+	service.service.mu.Unlock()
+
+	service.updateEdgeStacksAfterRelationChange(previousRelationState, updatedRelationState)
+
+	return nil
+}
+
+func (service ServiceTx) AddEndpointRelationsForEdgeStack(endpointIDs []portainer.EndpointID, edgeStack *portainer.EdgeStack) error {
+	for _, endpointID := range endpointIDs {
+		rel, err := service.EndpointRelation(endpointID)
+		if err != nil {
+			return err
+		}
+
+		rel.EdgeStacks[edgeStack.ID] = true
+
+		identifier := service.service.connection.ConvertToKey(int(endpointID))
+		err = service.tx.UpdateObject(BucketName, identifier, rel)
+		cache.Del(endpointID)
+		if err != nil {
+			return err
+		}
+	}
+
+	service.service.mu.Lock()
+	service.service.endpointRelationsCache = nil
+	service.service.mu.Unlock()
+
+	if err := service.service.updateStackFnTx(service.tx, edgeStack.ID, func(es *portainer.EdgeStack) {
+		es.NumDeployments += len(endpointIDs)
+
+		// sync changes in `edgeStack` in case it is re-persisted after `AddEndpointRelationsForEdgeStack` call
+		// to avoid overriding with the previous values
+		edgeStack.NumDeployments = es.NumDeployments
+	}); err != nil {
+		log.Error().Err(err).Msg("could not update the number of deployments")
+	}
+
+	return nil
+}
+
+func (service ServiceTx) RemoveEndpointRelationsForEdgeStack(endpointIDs []portainer.EndpointID, edgeStackID portainer.EdgeStackID) error {
+	for _, endpointID := range endpointIDs {
+		rel, err := service.EndpointRelation(endpointID)
+		if err != nil {
+			return err
+		}
+
+		delete(rel.EdgeStacks, edgeStackID)
+
+		identifier := service.service.connection.ConvertToKey(int(endpointID))
+		err = service.tx.UpdateObject(BucketName, identifier, rel)
+		cache.Del(endpointID)
+		if err != nil {
+			return err
+		}
+	}
+
+	service.service.mu.Lock()
+	service.service.endpointRelationsCache = nil
+	service.service.mu.Unlock()
+
+	if err := service.service.updateStackFnTx(service.tx, edgeStackID, func(edgeStack *portainer.EdgeStack) {
+		edgeStack.NumDeployments -= len(endpointIDs)
+	}); err != nil {
+		log.Error().Err(err).Msg("could not update the number of deployments")
+	}
+
+	return nil
+}
+
+// DeleteEndpointRelation deletes an Environment(Endpoint) relation object
+func (service ServiceTx) DeleteEndpointRelation(endpointID portainer.EndpointID) error {
+	deletedRelation, _ := service.EndpointRelation(endpointID)
+
+	identifier := service.service.connection.ConvertToKey(int(endpointID))
+	err := service.tx.DeleteObject(BucketName, identifier)
+	cache.Del(endpointID)
+	if err != nil {
+		return err
+	}
+
+	service.service.mu.Lock()
+	service.service.endpointRelationsCache = nil
+	service.service.mu.Unlock()
+
+	service.updateEdgeStacksAfterRelationChange(deletedRelation, nil)
+
+	return nil
+}
+
+func (service ServiceTx) InvalidateEdgeCacheForEdgeStack(edgeStackID portainer.EdgeStackID) {
+	rels, err := service.cachedEndpointRelations()
+	if err != nil {
+		log.Error().Err(err).Msg("cannot retrieve endpoint relations")
+		return
+	}
+
+	for _, rel := range rels {
+		if _, ok := rel.EdgeStacks[edgeStackID]; ok {
+			cache.Del(rel.EndpointID)
+		}
+	}
+}
+
+func (service ServiceTx) cachedEndpointRelations() ([]portainer.EndpointRelation, error) {
+	service.service.mu.Lock()
+	defer service.service.mu.Unlock()
+
+	if service.service.endpointRelationsCache == nil {
+		var err error
+		service.service.endpointRelationsCache, err = service.EndpointRelations()
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	return service.service.endpointRelationsCache, nil
+}
+
+func (service ServiceTx) updateEdgeStacksAfterRelationChange(previousRelationState *portainer.EndpointRelation, updatedRelationState *portainer.EndpointRelation) {
+	if previousRelationState != nil {
+		for stackId, enabled := range previousRelationState.EdgeStacks {
+			// flag stack for update if stack is not in the updated relation state
+			// = stack has been removed for this relation
+			// or this relation has been deleted
+			if enabled && (updatedRelationState == nil || !updatedRelationState.EdgeStacks[stackId]) {
+				if err := service.service.updateStackFnTx(service.tx, stackId, func(edgeStack *portainer.EdgeStack) {
+					// Sanity check
+					if edgeStack.NumDeployments <= 0 {
+						log.Error().
+							Int("edgestack_id", int(edgeStack.ID)).
+							Int("endpoint_id", int(previousRelationState.EndpointID)).
+							Int("num_deployments", edgeStack.NumDeployments).
+							Msg("cannot decrement the number of deployments for an edge stack with zero deployments")
+
+						return
+					}
+
+					edgeStack.NumDeployments--
+				}); err != nil {
+					log.Error().Err(err).Msg("could not update the number of deployments")
+				}
+
+				cache.Del(previousRelationState.EndpointID)
+			}
+		}
+	}
+
+	if updatedRelationState == nil {
+		return
+	}
+
+	for stackId, enabled := range updatedRelationState.EdgeStacks {
+		// flag stack for update if stack is not in the previous relation state
+		// = stack has been added for this relation
+		if enabled && (previousRelationState == nil || !previousRelationState.EdgeStacks[stackId]) {
+			if err := service.service.updateStackFnTx(service.tx, stackId, func(edgeStack *portainer.EdgeStack) {
+				edgeStack.NumDeployments++
+			}); err != nil {
+				log.Error().Err(err).Msg("could not update the number of deployments")
+			}
+
+			cache.Del(updatedRelationState.EndpointID)
+		}
+	}
+}

api/dataservices/errors/errors.go

@@ -0,0 +1,12 @@
+package errors
+
+import (
+	"errors"
+)
+
+var (
+	ErrObjectNotFound     = errors.New("object not found inside the database")
+	ErrWrongDBEdition     = errors.New("the Portainer database is set for Portainer Business Edition, please follow the instructions in our documentation to downgrade it: https://docs.portainer.io/faqs/upgrading/can-i-downgrade-from-portainer-business-to-portainer-ce")
+	ErrDBImportFailed     = errors.New("importing backup failed")
+	ErrDatabaseIsUpdating = errors.New("database is currently in updating state. Failed prior upgrade. Please restore from backup or delete the database and restart Portainer")
+)

api/dataservices/extension/extension.go

@@ -0,0 +1,66 @@
+package extension
+
+import (
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+// BucketName represents the name of the bucket where this service stores data.
+const BucketName = "extension"
+
+// Service represents a service for managing environment(endpoint) data.
+type Service struct {
+	connection portainer.Connection
+}
+
+func (service *Service) BucketName() string {
+	return BucketName
+}
+
+// NewService creates a new instance of a service.
+func NewService(connection portainer.Connection) (*Service, error) {
+	err := connection.SetServiceName(BucketName)
+	if err != nil {
+		return nil, err
+	}
+
+	return &Service{
+		connection: connection,
+	}, nil
+}
+
+// Extension returns a extension by ID
+func (service *Service) Extension(ID portainer.ExtensionID) (*portainer.Extension, error) {
+	var extension portainer.Extension
+	identifier := service.connection.ConvertToKey(int(ID))
+
+	err := service.connection.GetObject(BucketName, identifier, &extension)
+	if err != nil {
+		return nil, err
+	}
+
+	return &extension, nil
+}
+
+// Extensions return an array containing all the extensions.
+func (service *Service) Extensions() ([]portainer.Extension, error) {
+	var extensions = make([]portainer.Extension, 0)
+
+	return extensions, service.connection.GetAll(
+		BucketName,
+		&portainer.Extension{},
+		dataservices.AppendFn(&extensions),
+	)
+
+}
+
+// Persist persists a extension inside the database.
+func (service *Service) Persist(extension *portainer.Extension) error {
+	return service.connection.CreateObjectWithId(BucketName, int(extension.ID), extension)
+}
+
+// DeleteExtension deletes a Extension.
+func (service *Service) DeleteExtension(ID portainer.ExtensionID) error {
+	identifier := service.connection.ConvertToKey(int(ID))
+	return service.connection.DeleteObject(BucketName, identifier)
+}

api/dataservices/helmuserrepository/helmuserrepository.go

@@ -0,0 +1,53 @@
+package helmuserrepository
+
+import (
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+// BucketName represents the name of the bucket where this service stores data.
+const BucketName = "helm_user_repository"
+
+// Service represents a service for managing environment(endpoint) data.
+type Service struct {
+	dataservices.BaseDataService[portainer.HelmUserRepository, portainer.HelmUserRepositoryID]
+}
+
+// NewService creates a new instance of a service.
+func NewService(connection portainer.Connection) (*Service, error) {
+	err := connection.SetServiceName(BucketName)
+	if err != nil {
+		return nil, err
+	}
+
+	return &Service{
+		BaseDataService: dataservices.BaseDataService[portainer.HelmUserRepository, portainer.HelmUserRepositoryID]{
+			Bucket:     BucketName,
+			Connection: connection,
+		},
+	}, nil
+}
+
+// HelmUserRepositoryByUserID return an array containing all the HelmUserRepository objects where the specified userID is present.
+func (service *Service) HelmUserRepositoryByUserID(userID portainer.UserID) ([]portainer.HelmUserRepository, error) {
+	var result = make([]portainer.HelmUserRepository, 0)
+
+	return result, service.Connection.GetAll(
+		BucketName,
+		&portainer.HelmUserRepository{},
+		dataservices.FilterFn(&result, func(e portainer.HelmUserRepository) bool {
+			return e.UserID == userID
+		}),
+	)
+}
+
+// CreateHelmUserRepository creates a new HelmUserRepository object.
+func (service *Service) Create(record *portainer.HelmUserRepository) error {
+	return service.Connection.CreateObject(
+		BucketName,
+		func(id uint64) (int, any) {
+			record.ID = portainer.HelmUserRepositoryID(id)
+			return int(record.ID), record
+		},
+	)
+}

api/dataservices/helpers.go

@@ -0,0 +1,77 @@
+package dataservices
+
+import (
+	"errors"
+	"fmt"
+
+	perrors "github.com/portainer/portainer/api/dataservices/errors"
+
+	"github.com/rs/zerolog/log"
+)
+
+// ErrStop signals the stop of computation when filtering results
+var ErrStop = errors.New("stop")
+
+func IsErrObjectNotFound(e error) bool {
+	return errors.Is(e, perrors.ErrObjectNotFound)
+}
+
+// AppendFn appends elements to the given collection slice
+func AppendFn[T any](collection *[]T) func(obj any) (any, error) {
+	return func(obj any) (any, error) {
+		element, ok := obj.(*T)
+		if !ok {
+			log.Debug().Str("obj", fmt.Sprintf("%#v", obj)).Msg("type assertion failed")
+			return nil, fmt.Errorf("failed to convert to %T object: %#v", new(T), obj)
+		}
+
+		*collection = append(*collection, *element)
+
+		var zero T
+		*element = zero
+
+		return element, nil
+	}
+}
+
+// FilterFn appends elements to the given collection when the predicate is true
+func FilterFn[T any](collection *[]T, predicate func(T) bool) func(obj any) (any, error) {
+	return func(obj any) (any, error) {
+		element, ok := obj.(*T)
+		if !ok {
+			log.Debug().Str("obj", fmt.Sprintf("%#v", obj)).Msg("type assertion failed")
+			return nil, fmt.Errorf("failed to convert to %T object: %#v", new(T), obj)
+		}
+
+		if predicate(*element) {
+			*collection = append(*collection, *element)
+		}
+
+		var zero T
+		*element = zero
+
+		return element, nil
+	}
+}
+
+// FirstFn sets the element to the first one that satisfies the predicate and stops the computation, returns ErrStop on
+// success
+func FirstFn[T any](element *T, predicate func(T) bool) func(obj any) (any, error) {
+	return func(obj any) (any, error) {
+		e, ok := obj.(*T)
+		if !ok {
+			log.Debug().Str("obj", fmt.Sprintf("%#v", obj)).Msg("type assertion failed")
+			return nil, fmt.Errorf("failed to convert to %T object: %#v", new(T), obj)
+		}
+
+		if predicate(*e) {
+			*element = *e
+			return e, ErrStop
+		}
+
+		var zero T
+		*e = zero
+
+		return e, nil
+	}
+}

api/dataservices/interface.go

@@ -0,0 +1,282 @@
+package dataservices
+
+import (
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/database/models"
+)
+
+type (
+	DataStoreTx interface {
+		IsErrObjectNotFound(err error) bool
+		AllowList() AllowListService
+		CustomTemplate() CustomTemplateService
+		EdgeGroup() EdgeGroupService
+		EdgeJob() EdgeJobService
+		EdgeStack() EdgeStackService
+		EdgeStackStatus() EdgeStackStatusService
+		Endpoint() EndpointService
+		EndpointGroup() EndpointGroupService
+		EndpointRelation() EndpointRelationService
+		HelmUserRepository() HelmUserRepositoryService
+		Registry() RegistryService
+		ResourceControl() ResourceControlService
+		Role() RoleService
+		APIKeyRepository() APIKeyRepository
+		Settings() SettingsService
+		Snapshot() SnapshotService
+		SSLSettings() SSLSettingsService
+		Source() SourceService
+		Stack() StackService
+		Tag() TagService
+		TeamMembership() TeamMembershipService
+		Team() TeamService
+		TunnelServer() TunnelServerService
+		User() UserService
+		Version() VersionService
+		Webhook() WebhookService
+		Workflow() WorkflowService
+		PendingActions() PendingActionsService
+	}
+
+	DataStore interface {
+		Connection() portainer.Connection
+		Open() (newStore bool, err error)
+		Init() error
+		Close() error
+		UpdateTx(func(tx DataStoreTx) error) error
+		ViewTx(func(tx DataStoreTx) error) error
+		MigrateData() error
+		Rollback(force bool) error
+		CheckCurrentEdition() error
+		Backup(path string) (string, error)
+		Export(filename string) (err error)
+
+		DataStoreTx
+	}
+
+	// AllowListService represents a service for managing the URL allow list
+	AllowListService interface {
+		Read(id portainer.AllowListKey) (*portainer.AllowList, error)
+		ReadAll() ([]portainer.AllowList, error)
+		ReadParsed(id portainer.AllowListKey) (*portainer.ParsedAllowList, error)
+		Update(id portainer.AllowListKey, allowList *portainer.AllowList) error
+		BucketName() string
+	}
+
+	// CustomTemplateService represents a service to manage custom templates
+	CustomTemplateService interface {
+		BaseCRUD[portainer.CustomTemplate, portainer.CustomTemplateID]
+		GetNextIdentifier() int
+	}
+
+	// EdgeGroupService represents a service to manage Edge groups
+	EdgeGroupService interface {
+		BaseCRUD[portainer.EdgeGroup, portainer.EdgeGroupID]
+		UpdateEdgeGroupFunc(ID portainer.EdgeGroupID, updateFunc func(group *portainer.EdgeGroup)) error
+	}
+
+	// EdgeJobService represents a service to manage Edge jobs
+	EdgeJobService interface {
+		BaseCRUD[portainer.EdgeJob, portainer.EdgeJobID]
+		CreateWithID(ID portainer.EdgeJobID, edgeJob *portainer.EdgeJob) error
+		UpdateEdgeJobFunc(ID portainer.EdgeJobID, updateFunc func(edgeJob *portainer.EdgeJob)) error
+		GetNextIdentifier() int
+	}
+
+	PendingActionsService interface {
+		BaseCRUD[portainer.PendingAction, portainer.PendingActionID]
+		GetNextIdentifier() int
+		DeleteByEndpointID(ID portainer.EndpointID) error
+	}
+
+	// EdgeStackService represents a service to manage Edge stacks
+	EdgeStackService interface {
+		EdgeStacks() ([]portainer.EdgeStack, error)
+		EdgeStack(ID portainer.EdgeStackID) (*portainer.EdgeStack, error)
+		EdgeStackVersion(ID portainer.EdgeStackID) (int, bool)
+		Create(id portainer.EdgeStackID, edgeStack *portainer.EdgeStack) error
+		UpdateEdgeStack(ID portainer.EdgeStackID, edgeStack *portainer.EdgeStack) error
+		UpdateEdgeStackFunc(ID portainer.EdgeStackID, updateFunc func(edgeStack *portainer.EdgeStack)) error
+		DeleteEdgeStack(ID portainer.EdgeStackID) error
+		GetNextIdentifier() int
+		BucketName() string
+	}
+
+	EdgeStackStatusService interface {
+		Create(edgeStackID portainer.EdgeStackID, endpointID portainer.EndpointID, status *portainer.EdgeStackStatusForEnv) error
+		Read(edgeStackID portainer.EdgeStackID, endpointID portainer.EndpointID) (*portainer.EdgeStackStatusForEnv, error)
+		ReadAll(edgeStackID portainer.EdgeStackID) ([]portainer.EdgeStackStatusForEnv, error)
+		Update(edgeStackID portainer.EdgeStackID, endpointID portainer.EndpointID, status *portainer.EdgeStackStatusForEnv) error
+		Delete(edgeStackID portainer.EdgeStackID, endpointID portainer.EndpointID) error
+		DeleteAll(edgeStackID portainer.EdgeStackID) error
+		Clear(edgeStackID portainer.EdgeStackID, relatedEnvironmentsIDs []portainer.EndpointID) error
+	}
+
+	// EndpointService represents a service for managing environment(endpoint) data
+	EndpointService interface {
+		// partial dataservices.BaseCRUD[portainer.Endpoint, portainer.EndpointID]
+		ReadAll(predicates ...func(endpoint portainer.Endpoint) bool) ([]portainer.Endpoint, error)
+
+		Endpoint(ID portainer.EndpointID) (*portainer.Endpoint, error)
+		EndpointIDByEdgeID(edgeID string) (portainer.EndpointID, bool)
+		EndpointsByTeamID(teamID portainer.TeamID) ([]portainer.Endpoint, error)
+		Heartbeat(endpointID portainer.EndpointID) (int64, bool)
+		UpdateHeartbeat(endpointID portainer.EndpointID)
+		Endpoints() ([]portainer.Endpoint, error)
+		Create(endpoint *portainer.Endpoint) error
+		UpdateEndpoint(ID portainer.EndpointID, endpoint *portainer.Endpoint) error
+		DeleteEndpoint(ID portainer.EndpointID) error
+		GetNextIdentifier() int
+		BucketName() string
+	}
+
+	// EndpointGroupService represents a service for managing environment(endpoint) group data
+	EndpointGroupService interface {
+		BaseCRUD[portainer.EndpointGroup, portainer.EndpointGroupID]
+	}
+
+	// EndpointRelationService represents a service for managing environment(endpoint) relations data
+	EndpointRelationService interface {
+		EndpointRelations() ([]portainer.EndpointRelation, error)
+		EndpointRelation(EndpointID portainer.EndpointID) (*portainer.EndpointRelation, error)
+		Create(endpointRelation *portainer.EndpointRelation) error
+		UpdateEndpointRelation(EndpointID portainer.EndpointID, endpointRelation *portainer.EndpointRelation) error
+		AddEndpointRelationsForEdgeStack(endpointIDs []portainer.EndpointID, edgeStack *portainer.EdgeStack) error
+		RemoveEndpointRelationsForEdgeStack(endpointIDs []portainer.EndpointID, edgeStackID portainer.EdgeStackID) error
+		DeleteEndpointRelation(EndpointID portainer.EndpointID) error
+		BucketName() string
+	}
+
+	// HelmUserRepositoryService represents a service to manage HelmUserRepositories
+	HelmUserRepositoryService interface {
+		BaseCRUD[portainer.HelmUserRepository, portainer.HelmUserRepositoryID]
+		HelmUserRepositoryByUserID(userID portainer.UserID) ([]portainer.HelmUserRepository, error)
+	}
+
+	// RegistryService represents a service for managing registry data
+	RegistryService interface {
+		BaseCRUD[portainer.Registry, portainer.RegistryID]
+	}
+
+	// ResourceControlService represents a service for managing resource control data
+	ResourceControlService interface {
+		BaseCRUD[portainer.ResourceControl, portainer.ResourceControlID]
+		ResourceControlByResourceIDAndType(resourceID string, resourceType portainer.ResourceControlType) (*portainer.ResourceControl, error)
+	}
+
+	// RoleService represents a service for managing user roles
+	RoleService interface {
+		BaseCRUD[portainer.Role, portainer.RoleID]
+	}
+
+	// APIKeyRepositoryService
+	APIKeyRepository interface {
+		BaseCRUD[portainer.APIKey, portainer.APIKeyID]
+		GetAPIKeysByUserID(userID portainer.UserID) ([]portainer.APIKey, error)
+		GetAPIKeyByDigest(digest string) (*portainer.APIKey, error)
+	}
+
+	// SettingsService represents a service for managing application settings
+	SettingsService interface {
+		Settings() (*portainer.Settings, error)
+		UpdateSettings(settings *portainer.Settings) error
+		BucketName() string
+	}
+
+	SnapshotService interface {
+		BaseCRUD[portainer.Snapshot, portainer.EndpointID]
+		ReadWithoutSnapshotRaw(ID portainer.EndpointID) (*portainer.Snapshot, error)
+	}
+
+	// SSLSettingsService represents a service for managing application settings
+	SSLSettingsService interface {
+		Settings() (*portainer.SSLSettings, error)
+		UpdateSettings(settings *portainer.SSLSettings) error
+		BucketName() string
+	}
+
+	SourceServiceUserContext interface {
+		ID() portainer.UserID
+		TeamMemberships() []portainer.TeamMembership
+		IsAdmin() bool
+	}
+
+	// SourceService represents a service for managing GitOps source data
+	SourceService interface {
+		Create(context SourceServiceUserContext, source *portainer.Source) error
+		Read(context SourceServiceUserContext, ID portainer.SourceID) (*portainer.Source, error)
+		Exists(context SourceServiceUserContext, ID portainer.SourceID) (bool, error)
+		ReadAll(context SourceServiceUserContext, predicates ...func(portainer.Source) bool) ([]portainer.Source, error)
+		Update(context SourceServiceUserContext, ID portainer.SourceID, source *portainer.Source) error
+		Delete(context SourceServiceUserContext, ID portainer.SourceID) error
+		FindOrCreateGitSource(context SourceServiceUserContext, source *portainer.Source) (*portainer.Source, error)
+	}
+
+	// StackService represents a service for managing stack data
+	StackService interface {
+		BaseCRUD[portainer.Stack, portainer.StackID]
+		StackByName(name string) (*portainer.Stack, error)
+		StacksByName(name string) ([]portainer.Stack, error)
+		GetNextIdentifier() int
+		StackByWebhookID(ID string) (*portainer.Stack, error)
+		RefreshableStacks() ([]portainer.Stack, error)
+	}
+
+	// TagService represents a service for managing tag data
+	TagService interface {
+		BaseCRUD[portainer.Tag, portainer.TagID]
+		UpdateTagFunc(ID portainer.TagID, updateFunc func(tag *portainer.Tag)) error
+	}
+
+	// TeamService represents a service for managing user data
+	TeamService interface {
+		BaseCRUD[portainer.Team, portainer.TeamID]
+		TeamByName(name string) (*portainer.Team, error)
+	}
+
+	// TeamMembershipService represents a service for managing team membership data
+	TeamMembershipService interface {
+		BaseCRUD[portainer.TeamMembership, portainer.TeamMembershipID]
+		TeamMembershipsByUserID(userID portainer.UserID) ([]portainer.TeamMembership, error)
+		TeamMembershipsByTeamID(teamID portainer.TeamID) ([]portainer.TeamMembership, error)
+		DeleteTeamMembershipByUserID(userID portainer.UserID) error
+		DeleteTeamMembershipByTeamID(teamID portainer.TeamID) error
+		DeleteTeamMembershipByTeamIDAndUserID(teamID portainer.TeamID, userID portainer.UserID) error
+	}
+
+	// TunnelServerService represents a service for managing data associated to the tunnel server
+	TunnelServerService interface {
+		Info() (*portainer.TunnelServerInfo, error)
+		UpdateInfo(info *portainer.TunnelServerInfo) error
+		BucketName() string
+	}
+
+	// UserService represents a service for managing user data
+	UserService interface {
+		BaseCRUD[portainer.User, portainer.UserID]
+		UserByUsername(username string) (*portainer.User, error)
+		UserIDByUsername(username string) (portainer.UserID, error)
+		UsersByRole(role portainer.UserRole) ([]portainer.User, error)
+	}
+
+	// VersionService represents a service for managing version data
+	VersionService interface {
+		InstanceID() (string, error)
+		UpdateInstanceID(ID string) error
+		Edition() (portainer.SoftwareEdition, error)
+		Version() (*models.Version, error)
+		UpdateVersion(*models.Version) error
+	}
+
+	// WebhookService represents a service for managing webhook data.
+	WebhookService interface {
+		BaseCRUD[portainer.Webhook, portainer.WebhookID]
+		WebhookByResourceID(resourceID string) (*portainer.Webhook, error)
+		WebhookByToken(token string) (*portainer.Webhook, error)
+	}
+
+	// WorkflowService represents a service for managing GitOps workflow data
+	WorkflowService interface {
+		BaseCRUD[portainer.Workflow, portainer.WorkflowID]
+	}
+)

api/dataservices/pendingactions/pendingactions.go

@@ -0,0 +1,59 @@
+package pendingactions
+
+import (
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+const BucketName = "pending_actions"
+
+type Service struct {
+	dataservices.BaseDataService[portainer.PendingAction, portainer.PendingActionID]
+}
+
+func NewService(connection portainer.Connection) (*Service, error) {
+	err := connection.SetServiceName(BucketName)
+	if err != nil {
+		return nil, err
+	}
+
+	return &Service{
+		BaseDataService: dataservices.BaseDataService[portainer.PendingAction, portainer.PendingActionID]{
+			Bucket:     BucketName,
+			Connection: connection,
+		},
+	}, nil
+}
+
+// GetNextIdentifier returns the next identifier for a custom template.
+func (service *Service) GetNextIdentifier() int {
+	return service.Connection.GetNextIdentifier(BucketName)
+}
+
+func (s Service) Create(config *portainer.PendingAction) error {
+	return s.Connection.UpdateTx(func(tx portainer.Transaction) error {
+		return s.Tx(tx).Create(config)
+	})
+}
+
+func (s Service) Update(ID portainer.PendingActionID, config *portainer.PendingAction) error {
+	return s.Connection.UpdateTx(func(tx portainer.Transaction) error {
+		return s.Tx(tx).Update(ID, config)
+	})
+}
+
+func (s Service) DeleteByEndpointID(ID portainer.EndpointID) error {
+	return s.Connection.UpdateTx(func(tx portainer.Transaction) error {
+		return s.Tx(tx).DeleteByEndpointID(ID)
+	})
+}
+
+func (service *Service) Tx(tx portainer.Transaction) ServiceTx {
+	return ServiceTx{
+		BaseDataServiceTx: dataservices.BaseDataServiceTx[portainer.PendingAction, portainer.PendingActionID]{
+			Bucket:     BucketName,
+			Connection: service.Connection,
+			Tx:         tx,
+		},
+	}
+}

api/dataservices/pendingactions/pendingactions_test.go

@@ -0,0 +1,33 @@
+package pendingactions_test
+
+import (
+	"testing"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/datastore"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestDeleteByEndpoint(t *testing.T) {
+	t.Parallel()
+	_, store := datastore.MustNewTestStore(t, false, false)
+
+	// Create Endpoint 1
+	err := store.PendingActions().Create(&portainer.PendingAction{EndpointID: 1})
+	require.NoError(t, err)
+
+	// Create Endpoint 2
+	err = store.PendingActions().Create(&portainer.PendingAction{EndpointID: 2})
+	require.NoError(t, err)
+
+	// Delete Endpoint 1
+	err = store.PendingActions().DeleteByEndpointID(1)
+	require.NoError(t, err)
+
+	// Check that only Endpoint 2 remains
+	pendingActions, err := store.PendingActions().ReadAll()
+	require.NoError(t, err)
+	require.Len(t, pendingActions, 1)
+	require.Equal(t, portainer.EndpointID(2), pendingActions[0].EndpointID)
+}

api/dataservices/pendingactions/tx.go

@@ -0,0 +1,49 @@
+package pendingactions
+
+import (
+	"fmt"
+	"time"
+
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+	"github.com/rs/zerolog/log"
+)
+
+type ServiceTx struct {
+	dataservices.BaseDataServiceTx[portainer.PendingAction, portainer.PendingActionID]
+}
+
+func (s ServiceTx) Create(config *portainer.PendingAction) error {
+	return s.Tx.CreateObject(BucketName, func(id uint64) (int, any) {
+		config.ID = portainer.PendingActionID(id)
+		config.CreatedAt = time.Now().Unix()
+
+		return int(config.ID), config
+	})
+}
+
+func (s ServiceTx) Update(ID portainer.PendingActionID, config *portainer.PendingAction) error {
+	return s.BaseDataServiceTx.Update(ID, config)
+}
+
+func (s ServiceTx) DeleteByEndpointID(ID portainer.EndpointID) error {
+	log.Debug().Int("endpointId", int(ID)).Msg("deleting pending actions for endpoint")
+	pendingActions, err := s.ReadAll()
+	if err != nil {
+		return fmt.Errorf("failed to retrieve pending-actions for endpoint (%d): %w", ID, err)
+	}
+
+	for _, pendingAction := range pendingActions {
+		if pendingAction.EndpointID == ID {
+			if err := s.Delete(pendingAction.ID); err != nil {
+				log.Debug().Int("endpointId", int(ID)).Msgf("failed to delete pending action: %v", err)
+			}
+		}
+	}
+	return nil
+}
+
+// GetNextIdentifier returns the next identifier for a custom template.
+func (service ServiceTx) GetNextIdentifier() int {
+	return service.Tx.GetNextIdentifier(BucketName)
+}

api/dataservices/registry/registry.go

@@ -0,0 +1,50 @@
+package registry
+
+import (
+	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+)
+
+// BucketName represents the name of the bucket where this service stores data.
+const BucketName = "registries"
+
+// Service represents a service for managing environment(endpoint) data.
+type Service struct {
+	dataservices.BaseDataService[portainer.Registry, portainer.RegistryID]
+}
+
+// NewService creates a new instance of a service.
+func NewService(connection portainer.Connection) (*Service, error) {
+	err := connection.SetServiceName(BucketName)
+	if err != nil {
+		return nil, err
+	}
+
+	return &Service{
+		BaseDataService: dataservices.BaseDataService[portainer.Registry, portainer.RegistryID]{
+			Bucket:     BucketName,
+			Connection: connection,
+		},
+	}, nil
+}
+
+func (service *Service) Tx(tx portainer.Transaction) ServiceTx {
+	return ServiceTx{
+		BaseDataServiceTx: dataservices.BaseDataServiceTx[portainer.Registry, portainer.RegistryID]{
+			Bucket:     BucketName,
+			Connection: service.Connection,
+			Tx:         tx,
+		},
+	}
+}
+
+// Create creates a new registry.
+func (service *Service) Create(registry *portainer.Registry) error {
+	return service.Connection.CreateObject(
+		BucketName,
+		func(id uint64) (int, any) {
+			registry.ID = portainer.RegistryID(id)
+			return int(registry.ID), registry
+		},
+	)
+}